Overlay
Shiva

Covered the Shiva position-management layer plus a core Overlay pull request adding a liquidation callback, including a mid-review nonce management change.
report id
0438
category
DeFi & Yield
language
Solidity
final report
February 13, 2025
lines of code
701
Content

Download audit report

1

Executive Summary

This document presents the security review performed by Nethermind Security for Overlay Shiva smart contracts. Overlay Protocol is a decentralized platform allowing users to build positions on a market or data stream without traditional counterparties (liquidity providers or market makers) taking the other side. The protocol can offer markets on ANY non-manipulable & non-predictable numerical data feed.

Shiva is built on top of Overlay to manage positions across the multiple Overlay markets. Users can create and manage their positions in any Overlay market through Shiva, by doing this they get access to rewards from the Proof of Liquidity mechanism built in Berachain.

The audit comprises 701 lines of solidity code from the Shiva contracts and a Pull Request in the Overlay core contracts adding a callback to Shiva once a position gets liquidated. During the review, changes to nonce management were applied as a result of the Overlay and Nethermind teams' communication; the new implementation was also checked as part of the engagement.

The audit was performed using (a) manual analysis of the codebase, (b) automated analysis tools, and (c) creation of test cases.

Audit assessment
Audit TypeSecurity Review
Initial ReportFebruary 7, 2025
Final ReportFebruary 13, 2025
Repository (Shiva)v1-shiva
Commit9abeb89927
Repository (Core)v1-core
Pull RequestPR 207
Final Commit3e10c6099e
DocumentationREADME
Documentation AssessmentHigh
Test Suite AssessmentHigh
Total findings
2
Fixed
2
Acknowledged
0
Mitigated
0
Unresolved
0

Findings by severity

  • Critical0
  • High0
  • Medium0
  • Low0
  • Informational2
  • Best Practices0

2

Audited Files

#ContractLoCCommentsRatioBlankTotal
1src/ShivaStructs.sol3338115.2%576
2src/PolStakingToken.sol12541.7%421
3src/IShiva.sol57106186.0%21184
4src/Shiva.sol41025462.0%90754
5src/utils/Utils.sol824352.4%11136
6src/interfaces/aggregator/IFluxAggregator.sol9588.4%2105
7src/interfaces/berachain/IRewardVaults.sol12866.7%727
Total70146265.9%1401303

*The scope also includes the PR #207

4

System Overview

The Shiva contract is designed to interact with the Overlay protocol, providing a streamlined mechanism for building, unwinding, and managing positions in Overlay markets. Additionally, it integrates staking functionality via the BerachainRewardsVault, allowing users to stake their collateral and earn rewards.

Diagram from the audit report

4.1 Main interactions

Users interact with Shiva to manage positions in Overlay markets through three primary actions:

  • build: Opens a new position in an Overlay market. Users participating through Shiva can also earn rewards from the Proof of Liquidity (PoL) mechanism.
  • unwind: Allows users to partially or fully close a position. The user's PoL rewards adjust based on their new participation level.
  • buildSingle: Bundles an unwind and build action in the same market, effectively modifying an existing position. The user's remaining collateral from the unwind is used to open a new position in addition to any extra collateral provided.

These actions can also be executed on behalf of another user via a valid signed message, following the EIP-712.

4.2 Integration with Proof of Liquidity

Interacting with Overlay through Shiva enables users to participate in Berachain's PoL rewards system. When Shiva is deployed, it creates a dedicated RewardVault to facilitate staking for PoL rewards.

  • Every position opened through Shiva generates a receipt token, which is automatically staked in the RewardVault on behalf of the user.
  • Users receive PoL rewards based on their active participation in Overlay.
  • When a position is unwound or liquidated, Shiva unstakes and burns the corresponding receipt tokens.

4.3 Emergency Withdraw

If an Overlay market is shut down for any reason, users can retrieve their positions using the emergencyWithdraw(...) function. Importantly:

  • Even if a market is shut down, users continue earning PoL rewards until their positions are fully exited.
  • Any user can execute an emergency withdrawal for another user without restriction. This could incentivize users to process withdrawals on behalf of others, increasing their own share of PoL rewards.

4.4 Markets validation

Shiva only interacts with valid markets. A market is considered valid if it has been approved by any of the authorized factories.

  • The contract owner can add or remove authorized factories at any time.
  • While authorized factories can be removed, any market validated at any point remains permanently valid.

5

Risk Rating Methodology

The risk rating methodology used by Nethermind Security follows the principles established by the OWASP Foundation. The severity of each finding is determined by two factors: Likelihood and Impact.

Likelihood measures how likely the finding is to be uncovered and exploited by an attacker. This factor will be one of the following values:

  1. High: the issue is trivial to exploit and has no specific conditions that need to be met;
  2. Medium: the issue is moderately complex and may have some conditions that need to be met;
  3. Low: the issue is very complex and requires very specific conditions to be met.

When defining the likelihood of a finding, other factors are also considered. These can include but are not limited to motive, opportunity, exploit accessibility, ease of discovery, and ease of exploit.

Impact is a measure of the damage that may be caused if an attacker exploits the finding. This factor will be one of the following values:

  1. High: the issue can cause significant damage, such as loss of funds or the protocol entering an unrecoverable state;
  2. Medium: the issue can cause moderate damage, such as impacts that only affect a small group of users or only a particular part of the protocol;
  3. Low: the issue can cause little to no damage, such as bugs that are easily recoverable or cause unexpected interactions that cause minor inconveniences.

When defining the impact of a finding, other factors are also considered. These can include but are not limited to data and state integrity, loss of availability, financial loss, and reputation damage. After defining the likelihood and impact of an issue, the severity is determined according to the table below.

Impact / LikelihoodLowMediumHigh
HighMediumHighCritical
MediumLowMediumHigh
LowInfo / Best PracticesLowMedium
UndeterminedUndeterminedUndeterminedUndetermined

To address issues that do not fit a High, Medium or Low severity, Nethermind Security also uses three more finding severities: Informational, Best Practices, and Undetermined.

  1. Informational findings do not pose any risk to the application, but they carry some information that the audit team intends to pass to the client formally;
  2. Best Practice findings are used when some piece of code does not conform with smart contract development best practices;
  3. Undetermined findings are used when we cannot predict the impact or likelihood of the issue.

6

Issues

6.1 Donating ovl tokens can cause buildSingle operations to fail

FileFix commitTypeStatus
src/Shiva.sol—InfoFixed

The buildSingle operations allow users to unwind a position and build a new one in the same market using the withdrawn funds as part of the collateral for the new position.

function _buildSingleLogic(...) internal returns (...) {
require(_params.leverage >= ONE, "Shiva:lev<min");

// @audit - Unwind position
_onUnwindPosition(...);

// @audit - Compute collateral for the new positions using all the `ovl` tokens in the contract
uint256 totalCollateral = _params.collateral + ovlToken.balanceOf(address(this));
uint256 tradingFee = _getTradingFee(_params.ovlMarket, totalCollateral, _params.leverage);

bool isLong =
Utils.getPositionSide(_params.ovlMarket, _params.previousPositionId, address(this));

// @audit - Collect remaining tokens from user
// transfer from OVL from user to this contract
ovlToken.transferFrom(_owner, address(this), _params.collateral + tradingFee);

// Approve the ovlMarket contract to spend OVL
_approveMarket(_params.ovlMarket);

// @audit - Build new position
positionId = _onBuildPosition(...);
}

After unwinding the position, all ovl tokens held by the contract are considered as collateral for the new position. The trading fee is calculated based on the total collateral, which includes:

  • The ovl tokens already present in the contract, and;
  • The additional ovl tokens specified by the user;

Users are expected to compute the total collateral of the position before executing this call so they can set the correct allowance for the function.

However, an attacker could exploit this by donating small amounts of ovl tokens to the contract. Since the trading fee is based on the total collateral (which includes donated tokens), this could increase the required fee beyond the user's allowance. As a result, the transaction may fail due to insufficient allowance.

This failed transactions could result in a bad user experience.

Recommendation

To prevent unintended fee manipulation, consider tracking the ovl balance before and after calling _onUnwindPosition(...) and using only the actual unwound amount when computing collateral.

6.2 validMarkets(...) function may return incorrect results for uncached markets

FileFix commitTypeStatus
src/Shiva.sol—InfoFixed

The validMarkets mapping is used by the _checkIsValidMarket(...) function to cache valid markets.

/// @notice Mapping to check if an address is a valid market
mapping(address => bool) public validMarkets;

...

function _checkIsValidMarket(address _market) internal returns (bool) {
if (validMarkets[_market]) {
return true;
}

for (uint256 i = 0; i < authorizedFactories.length; i++) {
if (authorizedFactories[i].isMarket(_market)) {
validMarkets[_market] = true;

emit MarketValidated(_market);
return true;
}
}

return false;
}

The validMarkets mapping is public and a getter function for it is created automatically. While this function might appear to serve as a way to check whether a market is valid, it does not perform a full validation. Specifically, it returns false for valid markets that have not yet been cached by _checkIsValidMarket(...).

Recommendation

Consider changing the function to be private or internal if it is not intended to be used externally.

7

Documentation Evaluation

Software documentation refers to the written or visual information that describes the functionality, architecture, design, and implementation of software. It provides a comprehensive overview of the software system and helps users, developers, and stakeholders understand how the software works, how to use it, and how to maintain it. Software documentation can take different forms, such as user manuals, system manuals, technical specifications, requirements documents, design documents, and code comments. Software documentation is critical in software development, enabling effective communication between developers, testers, users, and other stakeholders. It helps to ensure that everyone involved in the development process has a shared understanding of the software system and its functionality. Moreover, software documentation can improve software maintenance by providing a clear and complete understanding of the software system, making it easier for developers to maintain, modify, and update the software over time. Smart contracts can use various types of software documentation. Some of the most common types include:

  • Technical whitepaper: A technical whitepaper is a comprehensive document describing the smart contract’s design and technical details. It includes information about the purpose of the contract, its architecture, its components, and how they interact with each other;
  • User manual: A user manual is a document that provides information about how to use the smart contract. It includes step-by-step instructions on how to perform various tasks and explains the different features and functionalities of the contract;
  • Code documentation: Code documentation is a document that provides details about the code of the smart contract. It includes information about the functions, variables, and classes used in the code, as well as explanations of how they work;
  • API documentation: API documentation is a document that provides information about the API (Application Programming Interface) of the smart contract. It includes details about the methods, parameters, and responses that can be used to interact with the contract;
  • Testing documentation: Testing documentation is a document that provides information about how the smart contract was tested. It includes details about the test cases that were used, the results of the tests, and any issues that were identified during testing;
  • Audit documentation: Audit documentation includes reports, notes, and other materials related to the security audit of the smart contract. This type of documentation is critical in ensuring that the smart contract is secure and free from vulnerabilities.

These types of documentation are essential for smart contract development and maintenance. They help ensure that the contract is properly designed, implemented, and tested, and they provide a reference for developers who need to modify or maintain the contract in the future.

8

Remarks & Test Suite

The Shiva team provided a document containing the multiple flows available for users. The repository contains a Readme explaining the multiple features implemented in the contract. Besides this information, the contracts contain many comments, and the team was available to answer any questions raised during the engagement.

As auditors, we recommend that any changes or updates made to the audited codebase undergo a re-audit or security review to address potential vulnerabilities or risks introduced by the modifications. By conducting a re-audit or security review of the modified codebase, you can significantly enhance the overall security of your system and reduce the likelihood of exploitation. However, we do not possess the authority or right to impose obligations or restrictions on our clients regarding codebase updates, modifications, or subsequent audits. Accordingly, the decision to seek a re-audit or security review lies solely with you.

This report is based on the scope of materials and documentation provided by you to Nethermind in order that Nethermind could conduct the security review outlined in 1. Executive Summary and 2. Audited Files. The results set out in this report may not be complete nor inclusive of all vulnerabilities. Nethermind has provided the review and this report on an as-is, where-is, and as-available basis. You agree that your access and/or use, including but not limited to any associated services, products, protocols, platforms, content, and materials, will be at your sole risk. Blockchain technology remains under development and is subject to unknown risks and flaws. The review does not extend to the compiler layer, or any other areas beyond the programming language, or other programming aspects that could present security risks. This report does not indicate the endorsement of any particular project or team, nor guarantee its security. No third party should rely on this report in any way, including for the purpose of making any decisions to buy or sell a product, service or any other asset. To the fullest extent permitted by law, Nethermind disclaims any liability in connection with this report, its content, and any related services and products and your use thereof, including, without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement. Nethermind does not warrant, endorse, guarantee, or assume responsibility for any product or service advertised or offered by a third party through the product, any open source or third-party software, code, libraries, materials, or information linked to, called by, referenced by or accessible through the report, its content, and the related services and products, any hyperlinked websites, any websites or mobile applications appearing on any advertising, and Nethermind will not be a party to or in any way be responsible for monitoring any transaction between you and any third-party providers of products or services. As with the purchase or use of a product or service through any medium or in any environment, you should use your best judgment and exercise caution where appropriate. FOR AVOIDANCE OF DOUBT, THE REPORT, ITS CONTENT, ACCESS, AND/OR USAGE THEREOF, INCLUDING ANY ASSOCIATED SERVICES OR MATERIALS, SHALL NOT BE CONSIDERED OR RELIED UPON AS ANY FORM OF FINANCIAL, INVESTMENT, TAX, LEGAL, REGULATORY, OR OTHER ADVICE.