Introduction
We express our gratitude to the TokenOps team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.
Token Vesting and Grant Distribution contracts set for Starknet Network provides a flexible and extensible framework for managing token vesting schedules and grant distributions. The contracts are designed to support a wide range of use cases, including employee compensation, advisor grants, community rewards, vestings, and more.
Document | |
|---|---|
| Name | Smart Contract Code Review and Security Analysis Report for TokenOps |
| Audited By | Stepan Chekhovskoi, Paul Clemson, Turgay Arda Usman |
| Approved By | Grzegorz Trawinski |
| Website | https://tokenops.xyz→ |
| Changelog | 28/10/2024 - Preliminary Report |
| 07/11/2024 - Final Report | |
| Platform | Starknet Network |
| Language | Cairo |
| Tags | Airdrop, Vesting |
| Methodology | https://hackenio.cc/sc_methodology→ |
Document
- Name
- Smart Contract Code Review and Security Analysis Report for TokenOps
- Audited By
- Stepan Chekhovskoi, Paul Clemson, Turgay Arda Usman
- Approved By
- Grzegorz Trawinski
- Website
- https://tokenops.xyz→
- Changelog
- 28/10/2024 - Preliminary Report
- 07/11/2024 - Final Report
- Platform
- Starknet Network
- Language
- Cairo
- Tags
- Airdrop, Vesting
- Methodology
- https://hackenio.cc/sc_methodology→
Review Scope | |
|---|---|
| Repository | https://github.com/VestingLabs/starknet_vesting→ |
| Initial Commit | 84645fe6cc4dafee6feda609656764d685ac13ae |
| Final Commit | c7df6a540645f8b78b52c1fc0462f253c56e7e4d |
Review Scope
- Initial Commit
- 84645fe6cc4dafee6feda609656764d685ac13ae
- Final Commit
- c7df6a540645f8b78b52c1fc0462f253c56e7e4d
Audit Summary
The system users should acknowledge all the risks summed up in the risks section of the report
Documentation quality
Features overview is presented.
Build instructions and tool versions are provided.
Code quality
The code is clearly written and mostly follows best practices.
The development environment is configured.
Test coverage
Code coverage of the project is 93.5% (line coverage).
The code common usecases are covered.
Various negative cases are covered.
System Overview
Token Vesting and Grant Distribution contracts set for Starknet Network provides Vesting Schedules functionality with some additional features.
The TokenVestingFactory contract implements ability for anyone to deploy the TokenVestingManager contract. The contract manages the contract class hash and allows owner to update it.
The TokenVestingManager contract allows the admin to create and revoke Vesting Schedules for specified recipients. The revocation does not impact the funds unlocked up to the Vesting Revoke.
The Vesting Schedule is implemented as follows: Start - Cliff - End.
Initial Unlock Amount it distributed at the Vesting Start.
Cliff Amount is distributed at the Vesting Cliff.
Linear Amount is linearly distributed between the Vesting Cliff (Vesting Start if Cliff not specified) and Vesting End with a specified Release Intervals.
There is a Timelock feature implemented which prohibits claim to occur before the Vesting Timelock ends. While the lock prevents claims, the system processes the accrued funds as unlocked and does not return them to admin in case of Vesting Revoke.
Privileged roles
The
TokenVestingFactorycontract Owner is able to update theTokenVestingManagercontract class hash. This does not impact deployed contracts but changes implementation for the contracts deployed after the change.The
TokenVestingManagercontract Admins are able to create and revoke Vesting Schedules keeping the funds integrity.
Potential Risks
Single Points of Failure and Control: The project is centralized, introducing single points of failure and control. This centralization may lead to vulnerabilities in decision-making and operational processes, making the system more susceptible to targeted attacks or manipulation.
Dynamic Array Iteration Gas Limit Risks: The project functions get_all_recipient_vestings and get_all_recipients iterate over large dynamic arrays, which may lead to excessive gas costs, risking denial of service due to out-of-gas errors.
Vesting Manager Class Hash Upgradeability: The TokenVestingFactory contract owner is able to update the recorded TokenVestingManager contract class hash. In case of a key leak, the class hash might be changed to a vulnerable one affecting the next TokenVestingManager contracts deployed.
Vesting Revocation Possibility: The TokenVestingManager contract admins are able to revoke any created vesting schedule withdrawing the undistributed funds. In case of a key leak, the malefactor may withdraw the funds and cause the token dump.
Findings
Code ― | Title | Status | Severity | |
|---|---|---|---|---|
| F-2024-6815 | Vesting Distribution Miscalculation due to Vesting Zero Duration | fixed | Medium | |
| F-2024-6811 | Vesting Claim and Revoke DoS due to Unexpectedly High Vesting Amount | mitigated | Medium | |
| F-2024-6810 | Initial Unlock Amount Accrued Before Vesting Start | fixed | Low | |
| F-2024-6809 | Potential Out of Bounds Error In Array Slice Getters | accepted | Observation | |
| F-2024-6777 | State Mutability can be Restricted to View | fixed | Observation | |
| F-2024-6776 | Event Misses Vesting ID Field | fixed | Observation | |
| F-2024-6774 | Missing Parameter Zero Validations | mitigated | Observation |
Identify vulnerabilities in your smart contracts.
Appendix 1. Definitions
Severities
When auditing smart contracts, Hacken is using a risk-based approach that considers Likelihood, Impact, Exploitability and Complexity metrics to evaluate findings and score severities.
Reference on how risk scoring is done is available through the repository in our Github organization:
Severity | Description |
|---|---|
Critical | Critical vulnerabilities are usually straightforward to exploit and can lead to the loss of user funds or contract state manipulation. |
High | High vulnerabilities are usually harder to exploit, requiring specific conditions, or have a more limited scope, but can still lead to the loss of user funds or contract state manipulation. |
Medium | Medium vulnerabilities are usually limited to state manipulations and, in most cases, cannot lead to asset loss. Contradictions and requirements violations. Major deviations from best practices are also in this category. |
Low | Major deviations from best practices or major Gas inefficiency. These issues will not have a significant impact on code execution. |
Severity
- Critical
Description
- Critical vulnerabilities are usually straightforward to exploit and can lead to the loss of user funds or contract state manipulation.
Severity
- High
Description
- High vulnerabilities are usually harder to exploit, requiring specific conditions, or have a more limited scope, but can still lead to the loss of user funds or contract state manipulation.
Severity
- Medium
Description
- Medium vulnerabilities are usually limited to state manipulations and, in most cases, cannot lead to asset loss. Contradictions and requirements violations. Major deviations from best practices are also in this category.
Severity
- Low
Description
- Major deviations from best practices or major Gas inefficiency. These issues will not have a significant impact on code execution.
Potential Risks
The "Potential Risks" section identifies issues that are not direct security vulnerabilities but could still affect the project’s performance, reliability, or user trust. These risks arise from design choices, architectural decisions, or operational practices that, while not immediately exploitable, may lead to problems under certain conditions. Additionally, potential risks can impact the quality of the audit itself, as they may involve external factors or components beyond the scope of the audit, leading to incomplete assessments or oversight of key areas. This section aims to provide a broader perspective on factors that could affect the project's long-term security, functionality, and the comprehensiveness of the audit findings.
Appendix 2. Scope
The scope of the project includes the following smart contracts from the provided repository:
Scope Details | |
|---|---|
| Repository | https://github.com/VestingLabs/starknet_vesting→ |
| Initial Commit | 84645fe6cc4dafee6feda609656764d685ac13ae |
| Final Commit | c7df6a540645f8b78b52c1fc0462f253c56e7e4d |
| Whitepaper | N/A |
| Requirements | README.md |
| Technical Requirements | README.md |
Scope Details
- Initial Commit
- 84645fe6cc4dafee6feda609656764d685ac13ae
- Final Commit
- c7df6a540645f8b78b52c1fc0462f253c56e7e4d
- Whitepaper
- N/A
- Requirements
- README.md
- Technical Requirements
- README.md
Assets in Scope
Appendix 3. Additional Valuables
Verification of System Invariants
During the audit of Token Vesting and Grant Distribution contracts set for Starknet Network, Hacken followed its methodology by performing fuzz-testing on the project's main functions. Starknet Foundry, a tool used for fuzz-testing, was employed to check how the protocol behaves under various inputs. Due to the complex and dynamic interactions within the protocol, unexpected edge cases might arise. Therefore, it was important to use fuzz-testing to ensure that several system invariants hold true in all situations.
Fuzz-testing allows the input of many random data points into the system, helping to identify issues that regular testing might miss. A specific Starknet Foundry fuzzing suite was prepared for this task, and throughout the assessment, 5 invariants were tested over 1M runs. This thorough testing ensured that the system works correctly even with unexpected or unusual inputs.
Invariant | Test Result | Run Count |
|---|---|---|
| Vesting funds should be distributed for various combinations of Claim and Revoke without leaving dust or breaking other Vestings consistency (for Vesting Linear Amount in u128 bounds). | Passed | 200K |
| Vesting funds should be distributed for various combinations of Claim and Revoke without leaving dust or breaking other Vestings consistency (for Vesting Initial Unlock Amount in u128 bounds). | Passed | 200K |
| Vesting funds should be distributed for various combinations of Claim and Revoke without leaving dust or breaking other Vestings consistency (for Vesting Cliff Amount in u128 bounds). | Passed | 200K |
| Vesting funds should be distributed with various Cliff (for valid Vesting Cliff times between Start and End of Vesting Schedule) | Passed | 200K |
| Vesting funds should be equal to the sum of funds received by user plus amount redeemable by admin in the event that Vesting Revoke | Passed | 200K |
Invariant
- Vesting funds should be distributed for various combinations of Claim and Revoke without leaving dust or breaking other Vestings consistency (for Vesting Linear Amount in u128 bounds).
Test Result
- Passed
Run Count
- 200K
Invariant
- Vesting funds should be distributed for various combinations of Claim and Revoke without leaving dust or breaking other Vestings consistency (for Vesting Initial Unlock Amount in u128 bounds).
Test Result
- Passed
Run Count
- 200K
Invariant
- Vesting funds should be distributed for various combinations of Claim and Revoke without leaving dust or breaking other Vestings consistency (for Vesting Cliff Amount in u128 bounds).
Test Result
- Passed
Run Count
- 200K
Invariant
- Vesting funds should be distributed with various Cliff (for valid Vesting Cliff times between Start and End of Vesting Schedule)
Test Result
- Passed
Run Count
- 200K
Invariant
- Vesting funds should be equal to the sum of funds received by user plus amount redeemable by admin in the event that Vesting Revoke
Test Result
- Passed
Run Count
- 200K
Additional Recommendations
The smart contracts in the scope of this audit could benefit from the introduction of automatic emergency actions for critical activities, such as unauthorized operations like ownership changes or proxy upgrades, as well as unexpected fund manipulations, including large withdrawals or minting events. Adding such mechanisms would enable the protocol to react automatically to unusual activity, ensuring that the contract remains secure and functions as intended.
To improve functionality, these emergency actions could be designed to trigger under specific conditions, such as:
Detecting changes to ownership or critical permissions.
Monitoring large or unexpected transactions and minting events.
Pausing operations when irregularities are identified.
These enhancements would provide an added layer of security, making the contract more robust and better equipped to handle unexpected situations while maintaining smooth operations.