PoolTogether - 0xepley's results

🛠️ PoolTogether

Conceptual overview of the project:

The PoolTogether project encapsulates a decentralized finance protocol, ingeniously designed to offer a no-loss savings game powered by yield-generating activities on the Ethereum blockchain. Essentially, it's a protocol where users' deposits are pooled together to earn yield, and this yield is then distributed as prizes, adding a gamified incentive to save.

At the heart of the project lies the PrizeVault contract, which is the cornerstone of the PoolTogether V5 upgrade. The PrizeVault, a smart contract built on top of the ERC4626 standard, serves as a depository for user funds. It interacts with an underlying yield vault to employ deposited assets in yield-generating strategies. The yields accrued are then periodically liquidated into a prize pool token and distributed as prizes among depositors, who stand a chance to win without risking their principal investment.

The process begins when users deposit their tokens into the PrizeVault. Upon deposit, the corresponding number of shares, which represent the depositor's stake in the vault, are minted. These shares are not just static representations of the user's balance but are dynamically tracked using a TWAB (Time-Weighted Average Balance) mechanism, which is capable of capturing the user’s historical balances. This TWAB mechanism, managed by a separate TwabController, allows the protocol to determine the depositor's eligibility for prizes over time.

The integration with the ERC4626 standard offers composability with other DeFi protocols and allows the PrizeVault to be an autonomous entity capable of yield farming. Furthermore, the PrizeVault contains mechanisms to mitigate rounding errors in yield accruals, ensuring that users can reclaim the exact amount of their initial deposits, thereby reinforcing the 'no-loss' essence of PoolTogether.

When the yield is generated, it triggers the liquidation process. Here, a liquidation pair is used to auction the yield for the prize token, which is then contributed to the Prize Pool. This process is governed by a set of timed auctions that ensure efficient price discovery and incentivize participants to complete these transactions promptly.

The project’s architecture also includes a Factory pattern through the PrizeVaultFactory contract, allowing for the streamlined creation of new PrizeVaults with custom parameters. It provides an easy way to scale and create multiple prize-generating pools with diverse underlying assets.

A Claimable extension is integrated within the PrizeVault, enabling automated prize claims using an external claimer contract. It also facilitates the users to set custom hooks, essentially callback functions that execute upon the claim event, offering a bespoke touch to the prize distribution.

<br/>

System Overview

Smart Contract: PrizeVault.sol

This is the heart of the protocol where users deposit their tokens. The deposited tokens are used within an underlying yield source to earn returns. The yield is then liquidated and contributed to the Prize Pool as prize tokens. When the Prize Pool awards a prize, the yield is distributed to the winner. This contract is also responsible for mitigating loss due to rounding errors, by employing strategies like the "dust collection strategy" and maintaining a "yield buffer".

Breakdown of Functions:

• Key Functions:

  • decimals: Defines the token's decimal precision.
  • totalAssets: Calculates the total assets within the vault.
  • convertToShares: Converts asset amounts to equivalent shares.
  • convertToAssets: Converts share amounts to equivalent assets.
  • maxDeposit: Determines the maximum deposit possible by an address.
  • maxMint: Calculates the maximum mintable shares.
  • maxWithdraw: Provides the maximum amount withdrawable by an owner.
  • maxRedeem: Returns the maximum shares redeemable by an owner.
  • previewDeposit: Forecasts shares for a given asset deposit.
  • previewMint: Estimates assets needed for minting shares.
  • previewWithdraw: Foresees shares needed to withdraw assets.
  • previewRedeem: Previews assets for redeeming shares.
  • deposit: Exchanges assets for share tokens.
  • mint: Mints shares in return for assets.
  • withdraw: Exchanges shares for underlying assets.
  • redeem: Redeems shares for assets.
  • sponsor: Deposits assets without becoming eligible for prizes.

• Liquidation Functions:

  • liquidatableBalanceOf: Returns the amount available for liquidation.
  • transferTokensOut: Transfers liquidated tokens out of the contract.
  • verifyTokensIn: Validates incoming tokens for liquidation.
  • targetOf: Indicates the target contract for liquidation.

• Yield Functions:

  • totalYieldBalance: Computes the total yield balance in the vault.
  • availableYieldBalance: Determines the yield available for use.
  • currentYieldBuffer: Returns the current yield buffer value.
  • claimYieldFeeShares: Claims shares of the yield fee.

• Administrative Functions:

  • setClaimer: Assigns the claimer contract.
  • setLiquidationPair: Sets the liquidation pair contract.
  • setYieldFeePercentage: Configures the yield fee percentage.
  • setYieldFeeRecipient: Specifies the recipient for yield fees.

• Yield-Related Adjustments:

  • depositWithPermit: Approves and deposits assets using a permit.

PrizeVaultFactory.sol

This contract is the manufacturing hub, so to speak, where new PrizeVault instances are minted. When deploying a PrizeVault, this factory contract initializes it with the necessary configurations, including the name, symbol, underlying yield vault, and the Prize Pool it contributes to. It also sends a starting balance to cover initial yield buffer requirements.

Key Functions:

• deployVault: Initiates a new PrizeVault instance.
• totalVaults: Counts all deployed PrizeVaults.

TwabERC20.sol

Think of this contract as a specialized accounting ledger that keeps track of the token balances in the PrizeVault. It records balances using the Time-Weighted Average Balance method, which is critical for calculating the chance of winning in the Prize Pool. It overrides standard ERC20 functions to integrate with the TwabController.

Key Functions:

• balanceOf: Returns the time-weighted balance of an account.
• totalSupply: Reflects the total supply with TWAB adjustments.

Token Transfer Overrides:

• _mint: Issues new tokens and logs them in TWAB.
• _burn: Destroys tokens and updates TWAB.
• _transfer: Moves tokens between accounts with TWAB recording.

Claimable.sol

This extension allows for prizes to be claimed on behalf of winners, enabling automated prize distribution. It integrates with the Prize Pool and can execute additional logic (hooks) before and after the prize claim event, allowing for custom actions like minting NFTs or triggering other smart contract functions.

Key Functions:

• claimPrize: Executes the prize claim process with optional hooks.
• _setClaimer: Internally sets the claiming agent.

HookManager.sol

This contract acts as a settings panel for users to manage their hooks.

Key Functions:

• getHooks: Retrieves the configured hooks for an account.
• setHooks: Allows a user to define their prize claim hooks.

IVaultHooks.sol

This interface defines the structure for the hooks themselves. Any smart contract that wishes to interact with PrizeVault via hooks must implement this interface. The hooks offer customizability and extend the PrizeVault's capabilities by introducing actions that occur in response to prize claims.

Prize Hook Categories:

• Before Claim Prize Hooks:
  • beforeClaimPrize: Hook to manage actions before prize claim.
• After Claim Prize Hooks:
  • afterClaimPrize: Hook to manage actions after prize claim.

Roles in the System

For each smart contract in the PoolTogether protocol, there are specific roles involved with distinct responsibilities. Here's a breakdown of these roles for each smart contracts:

PrizeVault.sol

• Admin/Owner Roles

  • Yield Management: Responsible for adjusting yield strategies, yield fee percentages, and yield buffer to optimize the prize generation process.
  • Relevant Code:

    function setYieldFeePercentage(uint32 _yieldFeePercentage) external onlyOwner {...}
    function setYieldFeeRecipient(address _yieldFeeRecipient) external onlyOwner {...}
    function setLiquidationPair(address _liquidationPair) external onlyOwner {...}

• User/Depositor Roles

  • Asset Management: Users are tasked with depositing assets and can manage their investments by withdrawing assets or redeeming them for shares.
  • Relevant Code:

    function withdraw(uint256 _assets, address _receiver, address _owner) external returns (uint256) {...}
    function redeem(uint256 _shares, address _receiver, address _owner) external returns (uint256) {...}

• Liquidation Pair

  • Liquidation Executor: A designated contract or address authorized to liquidate yield for prize distribution, managing the conversion of accrued yield into prizes.
  • Relevant Code:

    function transferTokensOut(address, address _receiver, address _tokenOut, uint256 _amountOut) public onlyLiquidationPair returns (bytes memory) {...}

• Yield Fee Recipient

  • Fee Collection: An entity designated to receive a portion of the yield as fees. This role involves claiming accumulated fees and managing them strategically.
  • Relevant Code:

        function claimYieldFeeShares(uint256 _shares) external onlyYieldFeeRecipient {...}

PrizeVaultFactory.sol

• Deployer: The entity that utilizes the factory to create new instances of PrizeVault.
  • Responsibility: To create new Prize Vaults with specific configurations tailored to different strategies or assets.
  • Relevant Code:

    function deployVault(...) external returns (PrizeVault) {...}

TwabERC20.sol

• Holder: Any entity that owns the token.
  • Responsibility: To participate in the protocol by holding tokens, which represent their share of the vault and eligibility for prizes.
  • Relevant Code:

    function balanceOf(address _account) public view virtual override(ERC20) returns (uint256) {...}

Claimable.sol

• Claimer: An external or integrated contract authorized to claim prizes on behalf of winners.
  • Responsibility: To facilitate the automated claiming of prizes, reducing the need for manual interaction by winners.
  • Relevant Code:

    function claimPrize(...) external onlyClaimer returns (uint256) {...}

• User/Winner: A user who has won a prize.
  • Responsibility: May set up hooks for automated actions upon winning a prize.
  • Relevant Code:

    // Users can manage hooks but specific code interaction is through claimPrize, managed by the Claimer.

HookManager.sol

• User: Anyone utilizing the protocol that wishes to add custom behavior upon winning prizes.
  • Responsibility: To define custom actions through hooks that execute in the context of prize claims.
  • Relevant Code:

    function setHooks(VaultHooks calldata hooks) external {...}

IVaultHooks.sol

• Developer/Implementer: The entity that develops custom hook contracts adhering to this interface.
  • Responsibility: To create innovative functionalities that can be executed before or after prizes are claimed, enhancing user experience or automating specific tasks.
  • Relevant Code:

    function beforeClaimPrize(...) external returns (address);
    function afterClaimPrize(...) external;

Codebase Quality

Overall, I consider the quality of the PoolTogether protocol codebase to be of high caliber. The codebase exhibits mature software engineering practices with a strong emphasis on security, modularity, and clear documentation. The smart contracts leverage established standards, which demonstrates adherence to best practices within the Ethereum development community. Details are explained below:

Mathematical Overview of the PoolTogether Protocol

The PoolTogether protocol incorporates various mathematical functions and principles to manage its prize-linked savings system. Below, we delve into the core mathematical aspects of the protocol, focusing primarily on the PrizeVault.sol contract, which plays a crucial role in managing user deposits, yield generation, and prize distribution.

Yield Generation and Distribution

1. Yield Buffer Management

The PrizeVault contract utilizes a yield buffer to ensure that small rounding errors in yield generation don't affect the user's ability to withdraw their full deposit. The yield buffer (yieldBuffer) is a predefined quantity of assets reserved to cover these errors.

2. Asset and Share Conversion

The protocol uses functions to convert between deposited assets and vault shares. These conversions account for the total debt (totalAssets - yieldBuffer) and the underlying yield vault's exchange rate to ensure users can always withdraw their deposits minus any incurred yield vault losses.

• Conversion to Shares:

  function convertToShares(uint256 _assets) public view returns (uint256) {
        uint256 totalDebt_ = totalDebt();
        uint256 _totalAssets = totalAssets();
        if (_totalAssets >= totalDebt_) {
            return _assets;
        } else {
            return _assets.mulDiv(totalDebt_, _totalAssets, Math.Rounding.Down);
        }
    }

• Conversion to Assets:

  function convertToAssets(uint256 _shares) public view returns (uint256) {
        uint256 totalDebt_ = totalDebt();
        uint256 _totalAssets = totalAssets();
        if (_totalAssets >= totalDebt_) {
            return _shares;
        } else {
            return _shares.mulDiv(_totalAssets, totalDebt_, Math.Rounding.Down);
        }
    }
  

3. Max Deposit and Withdraw Calculation

The maximum deposit and withdrawal amounts are dynamically calculated to ensure the vault's total share supply doesn't exceed the uint96 limit set by the TwabController, and to manage the total assets under yield generation without depleting the yield buffer.

• Max Deposit Calculation:

  function maxDeposit(address) public view returns (uint256) {
        uint256 _totalSupply = totalSupply();
        uint256 totalDebt_ = _totalDebt(_totalSupply);
        if (totalAssets() < totalDebt_) return 0;
  
        uint256 twabSupplyLimit_ = _twabSupplyLimit(_totalSupply);
        uint256 _maxDeposit;
        uint256 _latentBalance = _asset.balanceOf(address(this));
        uint256 _maxYieldVaultDeposit = yieldVault.maxDeposit(address(this));
        if (_latentBalance >= _maxYieldVaultDeposit) {
            return 0;
        } else {
            unchecked {
                _maxDeposit = _maxYieldVaultDeposit - _latentBalance;
            }
            return twabSupplyLimit_ < _maxDeposit ? twabSupplyLimit_ : _maxDeposit;
        }
    }

• Max Withdraw Calculation:

  function maxWithdraw(address _owner) public view returns (uint256) {
        uint256 _maxWithdraw = _maxYieldVaultWithdraw() + _asset.balanceOf(address(this));
  
        uint256 _ownerAssets = convertToAssets(balanceOf(_owner));
        return _ownerAssets < _maxWithdraw ? _ownerAssets : _maxWithdraw;
    }

4. Yield Fee and Liquidation

A portion of the generated yield is reserved as a fee, which can be claimed by a designated yield fee recipient. The liquidation process involves converting the generated yield into the prize token, taking into account the yield fee percentage.

• Yield Fee Calculation:

  function liquidatableBalanceOf(address _tokenOut) public view returns (uint256) {
        uint256 _totalSupply = totalSupply();
        uint256 _maxAmountOut;
        if (_tokenOut == address(this)) {
            // Liquidation of vault shares is capped to the TWAB supply limit.
            _maxAmountOut = _twabSupplyLimit(_totalSupply);
        } else if (_tokenOut == address(_asset)) {
            // Liquidation of yield assets is capped at the max yield vault withdraw plus any latent balance.
            _maxAmountOut = _maxYieldVaultWithdraw() + _asset.balanceOf(address(this));
        } else {
            return 0;
        }

• Fee Accrual and Claiming:

  function claimYieldFeeShares(uint256 _shares) external onlyYieldFeeRecipient {
        if (_shares == 0) revert MintZeroShares();
  
        uint256 _yieldFeeBalance = yieldFeeBalance;
        if (_shares > _yieldFeeBalance) revert SharesExceedsYieldFeeBalance(_shares, _yieldFeeBalance);
  
        yieldFeeBalance -= _yieldFeeBalance;
  
        _mint(msg.sender, _shares);
  
        emit ClaimYieldFeeShares(msg.sender, _shares);
    }

These mathematical functions ensure that the PoolTogether protocol can manage user deposits, generate yield, and distribute prizes in a secure and efficient manner. The interactions between these functions enable the protocol to adjust to changing conditions, such as yield rates and asset values, ensuring the sustainability of the prize-linked savings system.

Archietecture and WorkFlow

Comprehensive Flow Diagram of the PoolTogether Protocol

<br/>

Approach Taken while auditing the codebase

When auditing the PoolTogether protocol, I began by thoroughly reviewing the project documentation and existing audit reports. This initial step helped me understand the protocol's intended functionality, architecture, and security considerations from both a theoretical and a practical perspective.

Next, I delved into the smart contract codebase, starting with the core contracts such as PrizeVault.sol, PrizeVaultFactory.sol, and TwabERC20.sol, among others. My focus was to map out the interactions between these contracts and identify critical functionalities like asset deposits, yield generation, prize distribution, and the unique mathematical models used, including TWAB and random number generation.

To ensure a comprehensive audit, I analyzed the smart contracts for common vulnerabilities, such as reentrancy attacks, overflow/underflow issues, and improper access control. Special attention was given to the contracts' integration with external components like the Chainlink VRF and ERC4626 vaults, assessing how these interactions could impact the protocol's security.

I also scrutinized the protocol's handling of rounding errors and yield buffer management. Understanding these aspects was crucial, given their potential impact on prize distribution fairness and the overall "no loss" principle.

Moreover, I reviewed the tests accompanying the smart contracts to assess their coverage and effectiveness in catching edge cases and potential bugs. Wherever possible, I suggested improvements or additional test scenarios to enhance the protocol's robustness.

In summary, my auditing approach was methodical and thorough, combining a deep dive into the smart contracts, rigorous vulnerability assessment. My goal was to ensure the PoolTogether protocol's security, efficiency, and adherence to its innovative savings and prize distribution mechanisms.

Systemic Risks

Systemic risks in PoolTogether primarily revolve around the dependencies on external protocols and services for yield generation and randomness. The protocol's reliance on external ERC4626 yield vaults and RNG services introduces potential systemic vulnerabilities, including smart contract failures or manipulations in the integrated protocols.

The yieldVault from PrizeVault.sol represents an external dependency on ERC4626 yield sources. A systemic failure in the yield source could impact the prize vault's ability to generate yield and thereby prizes for users.

Centralization Risks

Centralization risks stem from the roles and permissions granted to certain addresses within the protocol. For instance, the ability of the admin or owner to adjust yield strategies and fee parameters introduces a central point of control.

Example Code:

function setYieldFeePercentage(uint32 _yieldFeePercentage) external onlyOwner {...}
function setYieldFeeRecipient(address _yieldFeeRecipient) external onlyOwner {...}
function setLiquidationPair(address _liquidationPair) external onlyOwner {...}

These functions in PrizeVault.sol allow the owner to modify critical financial parameters, presenting a centralization risk if the owner's address is compromised or if the owner acts maliciously.

Technical Risks

Smart Contract Vulnerabilities: Bugs or logical errors in the smart contracts can lead to loss of funds, unauthorized access, or unintended behavior. Given the complexity of contracts like the Shrine, interest rate models, and oracle interactions, the attack surface is significant.

Scalability Concerns: As transaction volumes grow, the platform must scale without compromising performance or security.

Integration Risks

Integration risks are primarily associated with the protocol's interactions with external DeFi platforms for yield generation and RNG services for random number generation. The protocol's security and functionality are contingent upon the reliability and integrity of these external services. Any changes or failures in the integrated platforms, such as smart contract upgrades, API modifications, or service discontinuations, could disrupt the protocol's operations. Moreover, the evolving landscape of DeFi presents a risk of compatibility issues, where updates in connected protocols could necessitate adjustments in PoolTogether's contracts to maintain seamless functionality and security.

New insights and learning of project from this audit:

During the audit of the PoolTogether project, several key insights and learning opportunities emerged, highlighting the project's innovative approach to decentralized finance and its integration within the Ethereum ecosystem. The audit provided a deep dive into the mechanics of no-loss prize games, the use of yield-generating strategies, and the complexities of smart contract development and security. Below are some of the primary insights and learnings derived from this audit:

1. No-Loss Prize Game Mechanics: The concept of no-loss prize games, where users deposit funds that generate yield in DeFi protocols, with the yield being distributed as prizes, is both innovative and complex. Understanding how PoolTogether manages user deposits, generates yield, and allocates prizes required a comprehensive analysis of the interactions between different smart contracts and external DeFi protocols.

2. Time-Weighted Average Balance (TWAB): The use of TWAB for fair and transparent prize distribution is a sophisticated approach to addressing the randomness and fairness in prize allocation. The audit process offered a deeper understanding of how TWAB works, including the mathematical principles underlying its implementation, and its significance in ensuring that the prize allocation process is both random and weighted towards users with longer deposit durations.

3. Security Implications of External Integrations: PoolTogether's reliance on external protocols for yield generation and random number generation (RNG) introduces various security considerations. The audit process emphasized the importance of evaluating the security and reliability of these external services, as well as the mechanisms through which PoolTogether interacts with them. This included an assessment of fallback procedures and contingency plans in case of external service failures.

4. Yield Strategies and Financial Risks: Analyzing the yield strategies employed by PoolTogether, including the integration with various DeFi yield sources, provided valuable insights into the financial risks and rewards associated with such strategies. The audit examined the mechanisms for optimizing yield generation, managing risks, and the potential impact of market volatility on the protocol's financial health.

The audit of PoolTogether not only highlighted the project's innovative contribution to the DeFi space but also provided a comprehensive learning experience on the technical, security, and financial aspects of building and maintaining a decentralized protocol. These insights are valuable for the ongoing development of PoolTogether, as well as for the broader DeFi community and future projects in the space.

NOTE: I don't track time while auditing or writing report, so what the time I specified is just a number

Time spent:

4 hours