Dev

.env.example

@@ -1,5 +1,4 @@
-export API_KEY_ALCHEMY="YOUR_API_KEY_ALCHEMY"
-export API_KEY_ETHERSCAN="YOUR_API_KEY_ETHERSCAN"
-export API_KEY_POLYGONSCAN="YOUR_API_KEY_POLYGONSCAN"
-export MNEMONIC="YOUR_MNEMONIC"
-export FOUNDRY_PROFILE="default"
+PRIVATE_KEY="PRIVATE_KEY"
+ALCHEMY_API_KEY="ALCHEMY_API_KEY"
+# Unified Etherscan V2 API key used by `rocketh-verify etherscan`
+ETHERSCAN_API_KEY="ETHERSCAN_API_KEY"

.gitignore

@@ -20,3 +20,4 @@ lcov.info
 artifacts
 cache_hardhat
 deployments
+generated

.prettierignore

@@ -17,3 +17,4 @@ package-lock.json
 pnpm-lock.yaml
 yarn.lock
 deployments
+.claude

CODE_OF_CONDUCT.md

@@ -0,0 +1,101 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for
+everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity
+and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion,
+or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take
+appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
+issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for
+moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing
+the community in public spaces. Examples of representing our community include using an official e-mail address, posting
+via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible
+for enforcement at contact@cooperlabs.xyz. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem
+in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the
+community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation
+and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including
+unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding
+interactions in community spaces as well as external channels like social media. Violating these terms may lead to a
+temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified
+period of time. No public or private interaction with the people involved, including unsolicited interaction with those
+enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate
+behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq.
+Translations are available at https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contribution Guidelines
+
+Thanks for your interest in contributing to the Transmuter system! Transmuter is a community built protocol and anyone
+is welcome to improve it.
+
+If you need to get in contact with the repository maintainers, please reach out in the
+[#community-dev channel](https://discord.gg/DgFR5T4DbM) of Parallel Discord Server.
+
+## Types of Contributing
+
+There are many ways to contribute, but here are a few if you want a place to start:
+
+1. **Opening an issue.** Before opening an issue, please check that there is not an issue already open. If there is,
+   feel free to comment more details, explanations, or examples within the open issue rather than duplicating it.
+   Suggesting changes to the open development process are within the bounds of opening issues. We are always open to
+   feedback and receptive to suggestions!
+2. **Resolving an issue.** You can resolve an issue either by showing that it is not an issue or by fixing the issue
+   with code changes, additional tests, etc. Any pull request fixing an issue should reference that issue.
+3. **Reviewing open PRs.** You can provide comments, standards guidance, naming suggestions, gas optimizations, or ideas
+   for alternative designs on any open pull request.
+
+## Opening an Issue
+
+When opening an [issue](https://github.com/parallel-protocol/parallel-parallelizer/issues), please title it with a
+concise problem statement and check that a similar request is not already open or in progress. Not all issues may be
+deemed worth resolving, so please follow through with responding to any questions or comments that others may have
+regarding the issue.
+
+## Opening a Pull Request
+
+All pull requests should be opened against the `main` branch. In the pull request, please reference the issue you are
+fixing.
+
+Pull requests can be reviewed by community members, but to be merged they will need approval from the repository
+maintainers. Please understand it will take time to receive a response, although the maintainers will aim to respond and
+comment as soon as possible.
+
+**For larger, more substantial changes to the code, it is best to open an issue and start a discussion with the
+maintainers to align on the change before spending time on the development.**
+
+Finally, before opening a pull request please do the following:
+
+- Run the Foundry tests with `bun run test`
+- Document any new functions, structs, or interfaces following the natspec standard.
+- Add tests! For smaller contributions, they should be tested with unit tests, and fuzz tests where possible. For bigger
+  contributions, they should be tested with invariant tests where possible.
+
+## Standards
+
+All contributions must follow the below standards. Maintainers will close out PRs that do not adhere to these standards.
+
+1. All contracts should be formatted with the prettier used in the default vscode config.
+2. These contracts follow the [solidity style guide](https://docs.soliditylang.org/en/v0.8.19/style-guide.html) with one
+   minor exception of using the `\_prependUnderscore` style naming for internal contract functions, internal top-level
+   parameters, and function parameters with naming collisions.
+3. All external facing contracts should inherit from interfaces, which specify and document its functions with natspec.
+4. Picking up stale issues by other authors is fine! Please just communicate with them ahead of time and it is best
+   practice to include co-authors in any commits.
+5. Squash commits where possible to make reviews clean and efficient. PRs that are merged to main will be squashed into
+   1 commit.
+
+## Code of Conduct
+
+Above all else, please be respectful of the people behind the code. Any kind of aggressive or disrespectful comments,
+issues, and language will be removed.
+
+Issues and PRs that are obviously spam and unhelpful to the development process or unrelated to the core code will also
+be closed.

README.md

@@ -1,6 +1,6 @@
 # Parallel Tokenomics
 
-## 1. Overview
+## Summary
 
 The Parallel Tokenomics system consists of smart contracts that enable:
 
@@ -29,30 +29,19 @@ The Parallel Tokenomics system consists of smart contracts that enable:
   - MainFeeDistributor: Mainnet
   - SideChainFeeDistributor: Polygon, Fantom
 
-The high-level architecture of the protocol is shown below:
+## Architecture
 
 ![High Level Architecture](./docs/assets/high-level-architecture.png)
 
-## 2. Folder Structure
-
-- [Broadcast](./broadcast) folder contains Foundry transactions executed by scripts.
-- [Contracts](./contracts) folder contains contracts source code.
-- [Deploy](./deploy) folder contains hardhat deployment scripts.
-- [Deployments](./deployments) folder contains info of contracts deployed per network.
-- [Docs](./docs) folder contains all documentation related to main contracts.
-- [Script](./scripts) folder contains Foundry scripts to interact with onchain contracts.
-- [Test](./test) folder contains all tests related to the contracts with mocks and settings.
-- [Utils](./utils) folder contains helper functions.
-
-## 3. Documentation
+## Documentation Links
 
 Additional documentation can be found in the `/docs` directory:
 
 - [Audit Details](docs/AuditDetails.md)
 - [Deployments Contracts](docs/Deployment.md)
 - [Technical Specifications](docs/TechnicalSpecs.md)
 
-## 4. Getting Started
+## Security
 
 ### Foundry
 
@@ -65,18 +54,14 @@ Foundry is used for testing and scripting. To
 bun i
 ```
 
-### Fill the `.env` file with your data
-
-The Foundry script relies solely on the PRIVATE_KEY. The MNEMONIC is used on the Hardhat side and will override the
-PRIVATE_KEY if it is defined.
+### Setup `.env` file
 
 ```bash
-export API_KEY_ALCHEMY="YOUR_API_KEY_ALCHEMY"
-export API_KEY_ETHERSCAN="YOUR_API_KEY_ETHERSCAN"
-export API_KEY_POLYGONSCAN="YOUR_API_KEY_POLYGONSCAN"
-export MNEMONIC="YOUR_MNEMONIC"
-export PRIVATE_KEY="YOUR_PRIVATE_KEY"
-export FOUNDRY_PROFILE="default"
+MNEMONIC="YOUR_MNEMONIC"
+PRIVATE_KEY="PRIVATE_KEY"
+ALCHEMY_API_KEY="ALCHEMY_API_KEY"
+MAINNET_ETHERSCAN_API_KEY="MAINNET_ETHERSCAN_API_KEY"
+POLYGON_ETHERSCAN_API_KEY="POLYGON_ETHERSCAN_API_KEY"
 ```
 
 ### Compile contracts
@@ -93,6 +78,20 @@ bun run test
 
 You will find other useful commands in the [package.json](./package.json) file.
 
-## Licences
+## Contributing
+
+If you're interested in contributing, please see our [contributions guidelines](./CONTRIBUTING.md).
+
+## Questions & Feedback
+
+For any question or feedback you can use [discord](https://discord.com/invite/mimodao). Don't hesitate to reach out on
+[Twitter](https://twitter.com/mimo_labs)🐦 as well.
+
+## Licensing
+
+The primary license for this repository is the MIT license. See [`LICENSE`](./LICENSE). Minus the following exceptions:
+
+- tests files are under UNLICENSED license
+- mocks contracts are under UNLICENSED license
 
-All contracts is under the `MIT` License, see [`LICENSE`](./LICENSE).
+Each of these files states their license type.

contracts/sPRL/TimeLockPenaltyERC20.sol

@@ -7,6 +7,7 @@ import { ERC20Votes } from "@openzeppelin/contracts/token/ERC20/extensions/ERC20
 import { IERC20Permit } from "@openzeppelin/contracts/token/ERC20/extensions/IERC20Permit.sol";
 import { ReentrancyGuard } from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { SafeERC20 } from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
 import { AccessManaged } from "@openzeppelin/contracts/access/manager/AccessManaged.sol";
 import { Pausable } from "@openzeppelin/contracts/utils/Pausable.sol";
 import { Nonces } from "@openzeppelin/contracts/utils/Nonces.sol";
@@ -22,6 +23,7 @@ import { MathsLib } from "contracts/libraries/MathsLib.sol";
 /// @custom:contact security@cooperlabs.xyz
 abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, AccessManaged, Pausable, ReentrancyGuard {
     using MathsLib for *;
+    using SafeERC20 for IERC20;
 
     //-------------------------------------------
     // Storage
@@ -115,6 +117,11 @@ abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, Access
     /// @param newPercentage The new penalty percentage.
     event StartPenaltyPercentageUpdated(uint256 oldPercentage, uint256 newPercentage);
 
+    /// @notice Emitted when extra tokens are recovered to the fee receiver.
+    /// @param token The address of the recovered token.
+    /// @param amount The amount of tokens recovered.
+    event TokensRecovered(address token, uint256 amount);
+
     //-------------------------------------------
     // Errors
     //-------------------------------------------
@@ -129,6 +136,12 @@ abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, Access
     error PercentageOutOfRange(uint256 attemptedPercentage);
     /// @notice Thrown when the penalty percentage is too high.
     error MaxPenaltyPercentageExceeded();
+    /// @notice Thrown when a withdrawal request is made with a zero amount.
+    error NullAmount();
+    /// @notice Thrown when the fee receiver is set to the zero address.
+    error FeeReceiverZeroAddress();
+    /// @notice Thrown when trying to recover the underlying token, which backs user shares.
+    error CannotRecoverUnderlying();
 
     //-------------------------------------------
     // Constructor
@@ -158,6 +171,9 @@ abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, Access
         if (_startPenaltyPercentage > MAX_PENALTY_PERCENTAGE) {
             revert PercentageOutOfRange(_startPenaltyPercentage);
         }
+        if (_feeReceiver == address(0)) {
+            revert FeeReceiverZeroAddress();
+        }
 
         feeReceiver = _feeReceiver;
         underlying = IERC20(_underlying);
@@ -172,6 +188,7 @@ abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, Access
     /// @notice Request to withdraw assets from the contract.
     /// @param _unlockingAmount The amount of assets to unlock.
     function requestWithdraw(uint256 _unlockingAmount) external {
+        if (_unlockingAmount == 0) revert NullAmount();
         _burn(msg.sender, _unlockingAmount);
 
         uint256 id = userVsNextID[msg.sender]++;
@@ -266,6 +283,9 @@ abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, Access
     /// @notice Allow the AccessManager to update the fee receiver address.
     /// @param _newFeeReceiver The new fee receiver.
     function updateFeeReceiver(address _newFeeReceiver) public virtual restricted {
+        if (_newFeeReceiver == address(0)) {
+            revert FeeReceiverZeroAddress();
+        }
         emit FeeReceiverUpdated(_newFeeReceiver);
         feeReceiver = _newFeeReceiver;
     }
@@ -282,6 +302,17 @@ abstract contract TimeLockPenaltyERC20 is ERC20, ERC20Permit, ERC20Votes, Access
         _unpause();
     }
 
+    /// @notice Recover extra tokens sitting idle in the contract (e.g. reward tokens sent on its behalf).
+    /// @dev The underlying token cannot be recovered as it backs user shares. Recovered tokens are sent to the fee
+    /// receiver.
+    /// @param _token The token to recover.
+    function recoverERC20(IERC20 _token) external restricted {
+        if (_token == underlying) revert CannotRecoverUnderlying();
+        uint256 balance = _token.balanceOf(address(this));
+        emit TokensRecovered(address(_token), balance);
+        _token.safeTransfer(feeReceiver, balance);
+    }
+
     //-------------------------------------------
     // Private/Internal functions
     //-------------------------------------------

contracts/sPRL/sPRL1.sol

@@ -32,13 +32,7 @@ contract sPRL1 is TimeLockPenaltyERC20 {
         uint64 _timeLockDuration
     )
         TimeLockPenaltyERC20(
-            NAME,
-            SYMBOL,
-            _underlying,
-            _feeReceiver,
-            _accessManager,
-            _startPenaltyPercentage,
-            _timeLockDuration
+            NAME, SYMBOL, _underlying, _feeReceiver, _accessManager, _startPenaltyPercentage, _timeLockDuration
         )
     { }
 
@@ -71,8 +65,9 @@ contract sPRL1 is TimeLockPenaltyERC20 {
         nonReentrant
     {
         // @dev using try catch to avoid reverting the transaction in case of front-running
-        try IERC20Permit(address(underlying)).permit(msg.sender, address(this), _assetAmount, _deadline, _v, _r, _s) {
-        } catch { }
+        try IERC20Permit(address(underlying))
+            .permit(msg.sender, address(this), _assetAmount, _deadline, _v, _r, _s) { }
+            catch { }
         underlying.safeTransferFrom(msg.sender, address(this), _assetAmount);
         _deposit(_assetAmount);
     }