Download audit report
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 Type | Security Review |
| Initial Report | February 7, 2025 |
| Final Report | February 13, 2025 |
| Repository (Shiva) | v1-shiva |
| Commit | 9abeb89927 |
| Repository (Core) | v1-core |
| Pull Request | PR 207 |
| Final Commit | 3e10c6099e |
| Documentation | README |
| Documentation Assessment | High |
| Test Suite Assessment | High |
Findings by severity
| # | Contract | LoC | Comments | Ratio | Blank | Total |
| 1 | src/ShivaStructs.sol | 33 | 38 | 115.2% | 5 | 76 |
| 2 | src/PolStakingToken.sol | 12 | 5 | 41.7% | 4 | 21 |
| 3 | src/IShiva.sol | 57 | 106 | 186.0% | 21 | 184 |
| 4 | src/Shiva.sol | 410 | 254 | 62.0% | 90 | 754 |
| 5 | src/utils/Utils.sol | 82 | 43 | 52.4% | 11 | 136 |
| 6 | src/interfaces/aggregator/IFluxAggregator.sol | 95 | 8 | 8.4% | 2 | 105 |
| 7 | src/interfaces/berachain/IRewardVaults.sol | 12 | 8 | 66.7% | 7 | 27 |
| Total | 701 | 462 | 65.9% | 140 | 1303 |
*The scope also includes the PR #207
| # | Finding | Severity | Update |
| 1 | Donating ovl tokens can cause buildSingle operations to fail | Info | Fixed |
| 2 | validMarkets(...) function may return incorrect results for uncached markets | Info | Fixed |
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.

Users interact with Shiva to manage positions in Overlay markets through three primary actions:
These actions can also be executed on behalf of another user via a valid signed message, following the EIP-712.
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.
If an Overlay market is shut down for any reason, users can retrieve their positions using the emergencyWithdraw(...) function. Importantly:
Shiva only interacts with valid markets. A market is considered valid if it has been approved by any of the authorized factories.
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:
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:
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 / Likelihood | Low | Medium | High |
| High | Medium | High | Critical |
| Medium | Low | Medium | High |
| Low | Info / Best Practices | Low | Medium |
| Undetermined | Undetermined | Undetermined | Undetermined |
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.
ovl tokens can cause buildSingle operations to fail| File | Fix commit | Type | Status |
src/Shiva.sol | — | Info | Fixed |
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:
ovl tokens already present in the contract, and;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.
validMarkets(...) function may return incorrect results for uncached markets| File | Fix commit | Type | Status |
src/Shiva.sol | — | Info | Fixed |
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.
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:
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.
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.
The Leading Engineers of Blockchain Infrastructure