Overlayer

We express our gratitude to the Overlayer team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

The Overlayer protocol is built on top of Ethereum to enhance existing stablecoins by minting overlaid assets backed by Aave. It embeds yield generation, censorship resistance, and trustless access directly into the asset design.

The system users should acknowledge all the risks summed up in the risks section of the report

{Finding_Table?columns=title,severity,status&setting.filter.type=Vulnerability}

Documentation quality

• NatSpec comments are comprehensive across all public and external functions.

• Technical description is provided via auto-generated solidity-docgen output and a README with mint/redeem/stake/compound flow overview.

• A formal protocol specification document (whitepaper or spec) is not provided.

Code quality

• The project makes extensive use of OpenZeppelin v5.0.2 contracts (ERC20, ERC4626, AccessControl, ReentrancyGuard, SafeERC20, Pausable) and LayerZero OFT for cross-chain functionality.

• The development environment is properly configured with multi-compiler Hardhat setup, Prettier formatting, and Solhint linting.

Test coverage

Code coverage of the project is 50% (branch coverage).

• Core user flows (mint, redeem, staking, cooldown, Aave supply/compound), negative cases, and multi-user scenarios are covered.

• Administrative lifecycle functions and the OverlayerBacking proxy have limited coverage.

Overlayer is a collateral-backed stablecoin protocol built on EVM-compatible chains. The system centers on OverlayerWrap, an ERC20 stablecoin with mint and redeem against configured collateral (and its Aave interest-bearing aToken). Minting and redeeming are rate-limited per block where minting can be paused; blacklisting is supported with a time-delayed activation (15 days). The protocol uses LayerZero OFT for cross-chain transfers to a designated hub chain.

Collateral is managed through a time-delayed collateral spender pattern: a new spender is proposed by a collateral manager role and must be accepted by the proposed contract after a 10-day interval, limiting single-point-of-failure risk. The OverlayerBacking contract acts as the backing manager entry point, inheriting AaveHandler to supply and withdraw collateral on Aave v3, compound yield, and distribute rewards between the staking vault and a protocol rewards dispatcher.

Staking is implemented via StakedOverlayerWrap, an ERC4626 vault that wraps OverlayerWrap. It supports a cooldown mechanism: when enabled, users request unstake and wait a configurable cooldown (up to 90 days) before withdrawing. During cooldown, shares are burned and the underlying tokens are held in OverlayerWrapSilo, which only the staking vault can withdraw from. StakedOverlayerWrapCore adds blacklisting (with time-delayed activation), redistribution of blacklisted balances, and reward distribution; it triggers backing compound() on mint to harvest yield before new share issuance.

The StakedOverlayerWrap vault does not implement explicit “rewards per share” or epoch-based accounting. Instead, yield is distributed implicitly through share price appreciation, consistent with the ERC4626 vault model, where rewards are reflected in totalAssets(). Deposits and withdrawals occur at the current share price, and deposit/withdraw operations trigger compound() before minting or burning shares. This ensures that accrued yield is realized and reflected in the vault state prior to share supply changes, preserving proportional ownership across participants.

Access control is implemented through SingleAdminAccessControl, a custom pattern on top of OpenZeppelin AccessControl with a single admin, two-step admin transfer (propose + accept), and restrictions on granting or renouncing the admin role directly.

Files in scope

• OverlayerWrap.sol – Primary stablecoin token contract. Implements ERC20 functionality and exposes mint and redeem entry points. Includes blacklisting functionality with time-delayed activation.

• OverlayerWrapCore.sol – Implements the core mint and redeem logic. Enforces per-block rate limiting (maximum mint/redeem per block with optional whitelist bypass), pause controls, collateral spender validation, and LayerZero OFT integration. Minting and redemption are restricted to the designated hub chain.

• CollateralSpenderManager.sol – Manages the collateral spender role with a time-delay mechanism. A new collateral spender must be proposed and can accept the role only after a 10-day delay. Only the proposed address may finalize acceptance. Exposes the currently approved collateral spender for collateral transfers.

• OverlayerWrapCollateral.sol – Stores collateral configuration parameters, including main collateral and corresponding aToken addresses and decimals. Serves as a base contract for collateral-aware components. Uses SingleAdminAccessControl for administrative initialization and management.

• StakedOverlayerWrap.sol – ERC4626-compliant staking vault for OverlayerWrap with an optional cooldown mechanism. When cooldown is enabled, users must request unstaking and wait for the cooldown period before claiming assets from the silo. May trigger backing compound(). Manages cooldown duration and silo integration.

• StakedOverlayerWrapCore.sol – Implements core staking functionality. Includes ERC4626 logic, blacklisting with time-delayed activation, redistribution of blacklisted balances, and reward distribution via transferInRewards().

• OverlayerWrapSilo.sol – Escrow contract used during the cooldown period. Holds OverlayerWrap tokens between unstake request and claim. Only the staking vault is authorized to withdraw funds.

• OverlayerBacking.sol – Entry point for backing allocation management. Inherits AaveHandler. Accepts the collateral spender role from OverlayerWrap and provides asset recovery functionality (excluding protocol-designated collateral).

• AaveHandler.sol – Integrates with Aave v3 for collateral supply and withdrawal. Implements yield compounding by minting OverlayerWrap from surplus aToken balances and distributing rewards between the staking vault and dispatcher. Supports time-delayed updates to the Aave pool and rewards allocation parameters. supply() is callable by OverlayerWrap; compound() is permissionless.

• SingleAdminAccessControl.sol – Custom access control module with a single default admin. Implements two-step admin transfer (propose and accept). Supports role grant, revoke, and renounce operations, with additional protection preventing external grant or renounce of the default admin role.

• OverlayerWrapCoreTypes.sol – Defines shared data structures used across the system, including:

• • Order (benefactor, beneficiary, collateral, amounts) for mint and redeem operations.

  • StableCoin (address, decimals) for collateral configuration.

Privileged roles

OverlayerWrap / OverlayerWrapCore:

• DEFAULT_ADMIN_ROLE - Grant/revoke all other roles; can call setMaxMintPerBlock, executeMaxRedeemPerBlockChange, proposeMaxRedeemPerBlock, whitelistMaxRedeemPerBlockUser, rescueNative; remove collateral managers ( removeCollateralManagerRole).

• GATEKEEPER_ROLE – can disable mint and pause/unpause supply backing functionality

• COLLATERAL_MANAGER_ROLE – can propose new collateral spender (10-day delay);  can call approveCollateral (approve token allowances for current spender).

• CONTROLLER_ROLE – can disableAccount / enableAccount enforsing blacklisting for the account.

• BLACKLISTED_ROLE – accounts with this role cannot mint, redeem, or transfer (treated as disabled).

CollateralSpenderManager:

• COLLATERAL_MANAGER_ROLE – can propose new collateral spender.

StakedOverlayerWrapCore:

• DEFAULT_ADMIN_ROLE – can manage OverlayerWrapBacking address.

• REWARDER_ROLE – can transfer OverlayerWrap rewards into the vault via transferInRewards().

• CONTROLLER_ROLE –  set blacklisted roles (when blacklist is active); can enable blacklist and redistribution by calling appropriately setBlackListTime / setRedistributionTime.

• STAKE_RESTRICTED_ROLE – account with this role cannot stake or receive shares via deposit/mint.

• WHOLE_RESTRICTED_ROLE – account with this role cannot transfer, stake, unstake, or withdraw; balance can be redistributed by admin via redistributeLockedAmount.

StakedOverlayerWrap:

• DEFAULT_ADMIN_ROLE – can call setCooldownDuration(), setWithdrawAaveDuringCompound()

OverlayerWrapSilo:

• _STAKING_VAULT – Only the staking vault address (immutable) can call withdraw.

OverlayerBacking:

• Owner –  accept collateral spender, recover non-protocol assets.

AaveHandler:

• Owner – admin withdraw, propose/accept Aave and dispatcher allocation, approvals; onlyProtocol for supply (OverlayerWrap only).

• OverlayerWrap (protocol) – only OverlayerWrap can call supply() (onlyProtocol).

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope