stQEUROToken

Git Source

Inherits: Initializable, ERC4626Upgradeable, AccessControlUpgradeable, PausableUpgradeable, ReentrancyGuardUpgradeable, SecureUpgradeable, IVersioned

Title: stQEUROToken

ERC-4626 vault over QEURO used for per-vault staking series.

Constants

GOVERNANCE_ROLE

bytes32 public constant GOVERNANCE_ROLE = keccak256("GOVERNANCE_ROLE")

EMERGENCY_ROLE

bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE")

VIRTUAL_SHARES

uint256 private constant VIRTUAL_SHARES = 1e12

TIME_PROVIDER

TimeProvider public immutable TIME_PROVIDER

State Variables

qeuro

IQEUROToken public qeuro

treasury

address public treasury

vaultName

string public vaultName

yieldFee

uint256 public yieldFee

accountedBalance

uint256 private accountedBalance

unvestedBalance

uint256 private unvestedBalance

vestingEnd

uint64 private vestingEnd

lastVestingUpdate

uint64 private lastVestingUpdate

vestingPeriod

uint32 public vestingPeriod

vestingInitialized

bool private vestingInitialized

virtualAssets

uint256 private virtualAssets

Functions

version

Returns the semantic version of this implementation.

Pure getter (no storage slot) read through the proxy, so it reflects the deployed implementation. Bump per semver on any change; enforced by make check-version-bump. See deployments/{chainId}/versions.json for the deployed impl/commit provenance.

Notes:

• security: No security implications - returns a compile-time constant.

• validation: No input validation required.

• state-changes: None - pure function.

• events: None.

• errors: None.

• reentrancy: Not applicable - pure function.

• access: Public - anyone can read the version.

• oracle: No oracle dependencies.

function version() external pure virtual override returns (string memory);

Returns

constructor

Constructs the implementation contract with its immutable time provider.

Validates the provided time provider, stores it immutably, and disables initializers on the implementation.

Notes:

• security: Rejects zero-address dependencies before deployment completes.

• validation: Ensures _TIME_PROVIDER is non-zero.

• state-changes: Sets the immutable TIME_PROVIDER reference and disables future initializers on the implementation.

• events: None.

• errors: Reverts with ZeroAddress when _TIME_PROVIDER is the zero address.

• reentrancy: Not applicable.

• access: Deployment only.

• oracle: Not applicable.

• oz-upgrades-unsafe-allow: constructor

constructor(TimeProvider _TIME_PROVIDER) ;

Parameters

_protocolTime

Returns canonical protocol time from this contract's TimeProvider

Overrides the SecureUpgradeable base, which returns block.timestamp.

Notes:

• security: Reads the immutable TimeProvider set at construction

• validation: None required

• state-changes: None

• events: None

• errors: None

• reentrancy: Read-only helper; no state mutation

• access: Internal helper

• oracle: No oracle dependencies

function _protocolTime() internal view override returns (uint256);

Returns

initialize

Initializes the default stQEURO vault series without a vault suffix.

Keeps the legacy initializer shape for factory compatibility, ignores unused placeholder addresses, and wires the ERC-4626 vault over QEURO.

Notes:

• security: Uses OpenZeppelin initializer guards and validates all named dependencies before role grants.

• validation: Ensures admin, token, treasury, and timelock dependencies are valid for vault setup.

• state-changes: Initializes ERC-20/ERC-4626 metadata, role assignments, treasury configuration, and the vault asset reference.

• events: Emits initialization events through inherited OpenZeppelin modules when applicable.

• errors: Reverts on duplicate initialization or invalid dependency addresses.

• reentrancy: Not applicable during initialization.

• access: Callable once during deployment.

• oracle: Not applicable.

function initialize(address admin, address _qeuro, address, address, address _treasury, address _timelock)
    public
    initializer;

Parameters

initialize

Initializes a vault-specific stQEURO series with custom metadata.

Builds vault-specific ERC-20 metadata, sets the ERC-4626 asset to QEURO, and applies secure-role configuration.

Notes:

• security: Uses initializer guards and validates critical dependency addresses before activation.

• validation: Ensures named dependencies are non-zero and treasury configuration is valid.

• state-changes: Initializes ERC-20/ERC-4626 metadata, stores vaultName, and grants operational roles.

• events: Emits initialization events through inherited OpenZeppelin modules when applicable.

• errors: Reverts on duplicate initialization or invalid dependency addresses.

• reentrancy: Not applicable during initialization.

• access: Callable once during deployment.

• oracle: Not applicable.

function initialize(address admin, address _qeuro, address _treasury, address _timelock, string calldata _vaultName)
    public
    initializer;

Parameters

_initializeStQEURODependencies

Applies the shared dependency and role setup for all stQEURO vault series.

Initializes inherited access-control, pause, reentrancy, and secure-upgrade modules, then stores treasury and QEURO references.

Notes:

• security: Centralizes all critical dependency validation before privileged roles are granted.

• validation: Requires non-zero admin/token/treasury addresses and a valid treasury destination.

• state-changes: Initializes inherited modules, grants roles, stores token/treasury references, and resets yieldFee to zero.

• events: Emits inherited role/admin initialization events when applicable.

• errors: Reverts on invalid addresses or treasury configuration failures.

• reentrancy: Not applicable.

• access: Internal initialization helper.

• oracle: Not applicable.

function _initializeStQEURODependencies(
    address admin,
    address qeuroAddress,
    address treasuryAddress,
    address timelockAddress
) internal;

Parameters

maxDeposit

Returns the maximum assets a receiver can deposit while respecting pause state.

Returns zero when the vault is paused and otherwise delegates limit calculation to the ERC-4626 parent implementation.

Notes:

• security: Read-only helper.

• validation: Paused state forces a zero limit.

• state-changes: None.

• events: None.

• errors: None.

• reentrancy: Not applicable.

• access: Public.

• oracle: Not applicable.

function maxDeposit(address receiver) public view override returns (uint256);

Parameters

Returns

maxMint

Returns the maximum shares a receiver can mint while respecting pause state.

Returns zero when the vault is paused and otherwise delegates limit calculation to the ERC-4626 parent implementation.

Notes:

• security: Read-only helper.

• validation: Paused state forces a zero limit.

• state-changes: None.

• events: None.

• errors: None.

• reentrancy: Not applicable.

• access: Public.

• oracle: Not applicable.

function maxMint(address receiver) public view override returns (uint256);

Parameters

Returns

maxWithdraw

Returns the maximum assets an owner can withdraw while respecting pause state.

Returns zero when the vault is paused and otherwise delegates limit calculation to the ERC-4626 parent implementation.

Notes:

• security: Read-only helper.

• validation: Paused state forces a zero limit.

• state-changes: None.

• events: None.

• errors: None.

• reentrancy: Not applicable.

• access: Public.

• oracle: Not applicable.

function maxWithdraw(address owner) public view override returns (uint256);

Parameters

Returns

maxRedeem

Returns the maximum shares an owner can redeem while respecting pause state.

Returns zero when the vault is paused and otherwise delegates limit calculation to the ERC-4626 parent implementation.

Notes:

• security: Read-only helper.

• validation: Paused state forces a zero limit.

• state-changes: None.

• events: None.

• errors: None.

• reentrancy: Not applicable.

• access: Public.

• oracle: Not applicable.

function maxRedeem(address owner) public view override returns (uint256);

Parameters

Returns

totalAssets

Returns only principal and the currently vested portion of yield.

Unvested underlying remains excluded from ERC-4626 share pricing.

Notes:

• security: Prevents a new depositor from immediately capturing harvested yield.

• validation: None; the raw underlying balance caps the result.

• state-changes: None.

• events: None.

• errors: None.

• reentrancy: Not applicable.

• access: Public view.

• oracle: No oracle dependency.

function totalAssets() public view override returns (uint256 assets);

Returns

_convertToShares

Converts assets using the series' matched virtual reserves.

Uses the same reserve quote before and after its first accounting synchronization.

Notes:

• security: Virtual shares preserve conversion precision at small real supply.

• validation: Checked arithmetic rejects unrepresentable totals.

• state-changes: None.

• events: None.

• errors: Arithmetic overflow.

• reentrancy: Read-only helper.

• access: Internal ERC-4626 conversion.

• oracle: None.

function _convertToShares(uint256 assets, Math.Rounding rounding) internal view override returns (uint256 shares);

Parameters

Returns

_convertToAssets

Converts shares using the series' matched virtual reserves.

Uses the same reserve as asset-to-share conversion without changing token decimals.

Notes:

• security: Keeps deposit and exit conversion symmetric.

• validation: Checked arithmetic rejects unrepresentable totals.

• state-changes: None.

• events: None.

• errors: Arithmetic overflow.

• reentrancy: Read-only helper.

• access: Internal ERC-4626 conversion.

• oracle: None.

function _convertToAssets(uint256 shares, Math.Rounding rounding) internal view override returns (uint256 assets);

Parameters

Returns

_virtualAssetReserve

Quotes the backing-bounded virtual asset reserve for this series.

Empty series start at parity. Existing populated series preserve their legacy (assets + 1) / (shares + 1) rate to within one virtual asset base unit. The same bound caps the reserve after losses so total redemption cannot exceed backing.

Notes:

• security: Scales reserves before the first supply change on an existing series.

• validation: Checked arithmetic and full-precision multiplication.

• state-changes: None.

• events: None.

• errors: Arithmetic overflow.

• reentrancy: Read-only helper.

• access: Internal.

• oracle: None.

function _virtualAssetReserve() private view returns (uint256 reserve);

Returns

deposit

Deposits QEURO into the vault and mints stQEURO shares to a receiver.

Wraps the ERC-4626 deposit flow with pause and reentrancy protection.

Notes:

• security: Protected by pause and nonReentrant guards.

• validation: Delegates asset, allowance, and receiver checks to ERC-4626/ERC-20 logic.

• state-changes: Transfers QEURO into the vault and mints new stQEURO shares.

• events: Emits the standard ERC-4626 Deposit event.

• errors: Reverts when paused or when ERC-20/ERC-4626 validations fail.

• reentrancy: Protected by nonReentrant.

• access: Public.

• oracle: Not applicable.

function deposit(uint256 assets, address receiver)
    public
    override
    nonReentrant
    whenNotPaused
    returns (uint256 shares);

Parameters

Returns

mint

Mints a target amount of stQEURO shares by supplying the required QEURO assets.

Wraps the ERC-4626 mint flow with pause and reentrancy protection.

Notes:

• security: Protected by pause and nonReentrant guards.

• validation: Delegates share, allowance, and receiver checks to ERC-4626/ERC-20 logic.

• state-changes: Transfers QEURO into the vault and mints stQEURO shares.

• events: Emits the standard ERC-4626 Deposit event.

• errors: Reverts when paused or when ERC-20/ERC-4626 validations fail.

• reentrancy: Protected by nonReentrant.

• access: Public.

• oracle: Not applicable.

function mint(uint256 shares, address receiver)
    public
    override
    nonReentrant
    whenNotPaused
    returns (uint256 assets);

Parameters

Returns

withdraw

Withdraws a target amount of QEURO assets from the vault.

Wraps the ERC-4626 withdraw flow with pause and reentrancy protection.

Notes:

• security: Protected by pause and nonReentrant guards.

• validation: Delegates asset, allowance, and balance checks to ERC-4626/ERC-20 logic.

• state-changes: Burns stQEURO shares and transfers QEURO assets out of the vault.

• events: Emits the standard ERC-4626 Withdraw event.

• errors: Reverts when paused or when ERC-20/ERC-4626 validations fail.

• reentrancy: Protected by nonReentrant.

• access: Public.

• oracle: Not applicable.

function withdraw(uint256 assets, address receiver, address owner)
    public
    override
    nonReentrant
    whenNotPaused
    returns (uint256 shares);

Parameters

Returns

redeem

Redeems stQEURO shares for their corresponding QEURO assets.

Wraps the ERC-4626 redeem flow with pause and reentrancy protection.

Notes:

• security: Protected by pause and nonReentrant guards.

• validation: Delegates share, allowance, and balance checks to ERC-4626/ERC-20 logic.

• state-changes: Burns stQEURO shares and transfers QEURO assets out of the vault.

• events: Emits the standard ERC-4626 Withdraw event.

• errors: Reverts when paused or when ERC-20/ERC-4626 validations fail.

• reentrancy: Protected by nonReentrant.

• access: Public.

• oracle: Not applicable.

function redeem(uint256 shares, address receiver, address owner)
    public
    override
    nonReentrant
    whenNotPaused
    returns (uint256 assets);

Parameters

Returns

_sweepResidualOnEmpty

Clears remaining QEURO after the final share exit.

Returns up to 1e12 wei of rounding dust to the receiver and sends excess to treasury.

Notes:

• security: Only reachable from nonReentrant exit paths; QEURO has no transfer hooks.

• validation: No-op unless the share supply is exactly zero.

• state-changes: Transfers bounded dust to receiver and excess to treasury.

• events: Emits ResidualSwept when a nonzero residue is transferred.

• errors: Reverts only if the underlying QEURO transfer fails.

• reentrancy: Callers hold the nonReentrant guard.

• access: Internal helper only.

• oracle: Not applicable.

function _sweepResidualOnEmpty(address receiver) private returns (uint256 residual);

Parameters

Returns

setVestingPeriod

Records a new governance-selected vesting period.

Synchronizes already-observed yield before changing the period used for future surplus.

Notes:

• security: Restricted to governance.

• validation: Rejects periods outside the bounded safety range.

• state-changes: Updates the future yield vesting period.

• events: Emits VestingPeriodUpdated.

• errors: ConfigValueTooLow or ConfigValueTooHigh.

• reentrancy: Not applicable.

• access: Governance role.

• oracle: No oracle dependency.

function setVestingPeriod(uint256 newPeriod) external onlyRole(GOVERNANCE_ROLE);

Parameters

syncVesting

Materializes currently vested yield and records newly observed surplus.

Permissionless during normal operation; governance may also sync during paused upgrades.

Notes:

• security: Paused maintenance requires governance authorization.

• validation: Underlying balance deltas are bounded by the token balance.

• state-changes: Updates principal, unvested yield, and vesting timestamps.

• events: Emits YieldVestingSynced.

• errors: AccessControlUnauthorizedAccount for non-governance callers while paused.

• reentrancy: Protected by nonReentrant.

• access: Public when unpaused; GOVERNANCE_ROLE while paused.

• oracle: No oracle dependency.

function syncVesting() external nonReentrant;

_syncVestingAccounting

function _syncVestingAccounting() private;

_vestedBalanceView

function _vestedBalanceView() private view returns (uint256 vested);

transfer

Transfers stQEURO shares while the vault is active.

Blocks share transfers whenever the vault is paused.

Notes:

• security: Protected by the pause guard.

• validation: Delegates recipient, balance, and amount checks to ERC-20 logic.

• state-changes: Moves stQEURO share balances between accounts.

• events: Emits the standard ERC-20 Transfer event.

• errors: Reverts when paused or when ERC-20 validations fail.

• reentrancy: Not applicable.

• access: Public.

• oracle: Not applicable.

function transfer(address to, uint256 value)
    public
    override(ERC20Upgradeable, IERC20)
    whenNotPaused
    returns (bool);

Parameters

Returns

transferFrom

Transfers stQEURO shares from another account while the vault is active.

Blocks allowance-based share transfers whenever the vault is paused.

Notes:

• security: Protected by the pause guard.

• validation: Delegates allowance, recipient, balance, and amount checks to ERC-20 logic.

• state-changes: Moves stQEURO share balances between accounts and updates allowance when applicable.

• events: Emits the standard ERC-20 Transfer event and allowance events when applicable.

• errors: Reverts when paused or when ERC-20 validations fail.

• reentrancy: Not applicable.

• access: Public.

• oracle: Not applicable.

function transferFrom(address from, address to, uint256 value)
    public
    override(ERC20Upgradeable, IERC20)
    whenNotPaused
    returns (bool);

Parameters

Returns

updateYieldParameters

Updates the yield fee charged on compounded vault yield.

Governance can set the fee in basis points up to the configured 20% cap.

Notes:

• security: Restricted to GOVERNANCE_ROLE.

• validation: Validates _yieldFee against the 2000 bps maximum.

• state-changes: Updates the stored yieldFee.

• events: Emits YieldParametersUpdated.

• errors: Reverts on invalid fee values or missing governance role.

• reentrancy: Not applicable.

• access: Restricted to GOVERNANCE_ROLE.

• oracle: Not applicable.

function updateYieldParameters(uint256 _yieldFee) external onlyRole(GOVERNANCE_ROLE);

Parameters

updateTreasury

Updates the treasury destination used for recovery flows.

Governance can rotate the treasury after standard non-zero and treasury-address validation passes.

Notes:

• security: Restricted to GOVERNANCE_ROLE.

• validation: Requires a non-zero address that passes treasury validation rules.

• state-changes: Replaces the stored treasury address.

• events: Emits TreasuryUpdated.

• errors: Reverts on invalid treasury addresses or missing governance role.

• reentrancy: Not applicable.

• access: Restricted to GOVERNANCE_ROLE.

• oracle: Not applicable.

function updateTreasury(address _treasury) external onlyRole(GOVERNANCE_ROLE);

Parameters

pause

Pauses deposits, withdrawals, redemptions, and share transfers.

Emergency role can freeze vault interactions until the pause is lifted.

Notes:

• security: Restricted to EMERGENCY_ROLE.

• validation: None.

• state-changes: Sets the paused state to true.

• events: Emits the inherited Paused event.

• errors: Reverts on missing emergency role or if already paused.

• reentrancy: Not applicable.

• access: Restricted to EMERGENCY_ROLE.

• oracle: Not applicable.

function pause() external onlyRole(EMERGENCY_ROLE);

unpause

Unpauses deposits, withdrawals, redemptions, and share transfers.

Emergency role can resume normal vault operation after a pause.

Notes:

• security: Restricted to EMERGENCY_ROLE.

• validation: None.

• state-changes: Sets the paused state to false.

• events: Emits the inherited Unpaused event.

• errors: Reverts on missing emergency role or if the vault is not paused.

• reentrancy: Not applicable.

• access: Restricted to EMERGENCY_ROLE.

• oracle: Not applicable.

function unpause() external onlyRole(EMERGENCY_ROLE);

emergencyWithdraw

Forces a full emergency redemption of a user's stQEURO position.

Emergency role can burn all of a user's shares and transfer the current redeemable QEURO balance directly to that user.

Notes:

• security: Restricted to EMERGENCY_ROLE and protected by nonReentrant.

• validation: Returns early when user holds no shares.

• state-changes: Burns the user's full share balance and transfers corresponding QEURO assets out of the vault.

• events: Emits the standard ERC-4626 Withdraw event when shares are burned.

• errors: Reverts on missing emergency role or failed asset transfer.

• reentrancy: Protected by nonReentrant.

• access: Restricted to EMERGENCY_ROLE.

• oracle: Not applicable.

function emergencyWithdraw(address user) external onlyRole(EMERGENCY_ROLE) nonReentrant;

Parameters

recoverToken

Recovers non-QEURO ERC-20 tokens mistakenly sent to the vault.

Admin-only recovery route forwards unsupported tokens to the configured treasury and explicitly forbids recovering the underlying asset.

Notes:

• security: Restricted to DEFAULT_ADMIN_ROLE and blocks recovery of the vault's underlying asset.

• validation: Requires token to differ from asset().

• state-changes: Transfers the specified token amount from the vault to the treasury.

• events: Emits downstream ERC-20 Transfer events from the recovered token.

• errors: Reverts on invalid token selection, failed transfers, or missing admin role.

• reentrancy: Not applicable.

• access: Restricted to DEFAULT_ADMIN_ROLE.

• oracle: Not applicable.

function recoverToken(address token, uint256 amount) external onlyRole(DEFAULT_ADMIN_ROLE);

Parameters

recoverETH

Recovers native ETH held by the vault and forwards it to the treasury.

Admin-only recovery route sends the contract's entire ETH balance to the configured treasury.

Notes:

• security: Restricted to DEFAULT_ADMIN_ROLE.

• validation: Requires a configured treasury and a positive ETH balance.

• state-changes: Transfers the full native ETH balance from the vault to the treasury.

• events: Emits ETHRecovered.

• errors: Reverts on missing treasury, zero ETH balance, send failure, or missing admin role.

• reentrancy: Not applicable.

• access: Restricted to DEFAULT_ADMIN_ROLE.

• oracle: Not applicable.

function recoverETH() external onlyRole(DEFAULT_ADMIN_ROLE);

Events

YieldParametersUpdated

event YieldParametersUpdated(uint256 yieldFee);

TreasuryUpdated

event TreasuryUpdated(address indexed oldTreasury, address indexed newTreasury, address indexed caller);

ETHRecovered

event ETHRecovered(address indexed to, uint256 indexed amount);

ResidualSwept

Emitted when the rounding residue left by the final exit is swept to its receiver

event ResidualSwept(address indexed receiver, uint256 amount);

VestingPeriodUpdated

event VestingPeriodUpdated(uint256 oldPeriod, uint256 newPeriod);

YieldVestingSynced

event YieldVestingSynced(uint256 vested, uint256 unvested, uint256 accounted);