Natspec Standards

/// @title Staking Vault
/// @author Uniswap Labs
/// @notice Handles staking deposits and reward distribution for protocol governance tokens.
/// @dev Uses ERC-4626 vault standard with custom reward distribution.
///      Storage layout is proxy-compatible (see storage-layout skill).
/// @custom:security-contact security@uniswap.org
contract StakingVault is ERC4626, Ownable2Step, ReentrancyGuard {
    // ...
}

/// @notice Deposits tokens into the vault and mints shares to the caller.
/// @dev Follows CEI pattern. Emits {Deposited} event. The share calculation
///      uses the current exchange rate, which may be manipulated in the same
///      block — see economic-attack-vectors for first-depositor defense.
/// @param token The address of the ERC-20 token to deposit.
/// @param amount The amount of tokens to deposit (in token's native decimals).
/// @return shares The number of vault shares minted to the caller.
function deposit(address token, uint256 amount)
    external
    nonReentrant
    whenNotPaused
    returns (uint256 shares)
{
    if (token == address(0)) revert ZeroAddress();
    if (amount == 0) revert ZeroAmount();

    shares = convertToShares(amount);
    _mint(msg.sender, shares);

    IERC20(token).safeTransferFrom(msg.sender, address(this), amount);

    emit Deposited(msg.sender, token, amount, shares);
}

/// @notice Returns the position details for a given position ID.
/// @param positionId The unique identifier of the position.
/// @return owner The address that owns the position.
/// @return collateral The amount of collateral deposited (in token decimals).
/// @return debt The amount of debt owed (in token decimals).
/// @return healthFactor The position's health factor (18 decimals, < 1e18 = liquidatable).
function getPosition(uint256 positionId)
    external
    view
    returns (
        address owner,
        uint256 collateral,
        uint256 debt,
        uint256 healthFactor
    )
{
    // ...
}

interface IVault {
    /// @notice Withdraws tokens by burning vault shares.
    /// @param shares The number of shares to burn.
    /// @return amount The number of tokens returned to the caller.
    function withdraw(uint256 shares) external returns (uint256 amount);
}

contract Vault is IVault {
    /// @inheritdoc IVault
    /// @dev Applies a withdrawal fee of 0.1% (10 bps). The fee is retained
    ///      in the vault, increasing the share price for remaining holders.
    function withdraw(uint256 shares) external override returns (uint256 amount) {
        // ...
    }
}

/// @notice Emitted when a user deposits tokens into the vault.
/// @param user The address of the depositor.
/// @param token The address of the deposited token.
/// @param amount The amount deposited (in token's native decimals).
/// @param shares The number of vault shares minted.
event Deposited(address indexed user, address indexed token, uint256 amount, uint256 shares);

/// @dev Thrown when the oracle price feed returns data older than the staleness threshold.
/// @param feed The address of the Chainlink price feed.
/// @param updatedAt The timestamp of the last price update.
/// @param threshold The maximum allowed age in seconds.
error Oracle_StalePrice(address feed, uint256 updatedAt, uint256 threshold);

/// @custom:security-contact security@protocol.xyz
/// @custom:oz-upgrades-from StakingVaultV1
/// @custom:storage-location erc7201:protocol.storage.StakingVault
contract StakingVaultV2 is StakingVaultV1 {
    // ...
}

/// @dev Restricts function access to the designated oracle updater.
///      Reverts with {Unauthorized} if caller is not the updater.
modifier onlyUpdater() {
    if (msg.sender != updater) revert Unauthorized();
    _;
}

/// @notice Represents a user's staking position.
/// @dev Packed into 2 storage slots (64 bytes). See storage-layout skill.
/// @param amount The staked token amount (18 decimals).
/// @param rewardDebt Used for reward accounting (scaled by ACC_PRECISION).
/// @param lockEnd The timestamp when the lock period expires.
/// @param boostMultiplier The user's boost factor (100 = 1x, 200 = 2x).
struct StakeInfo {
    uint256 amount;
    uint256 rewardDebt;
    uint48 lockEnd;
    uint16 boostMultiplier;
}