time-manipulation

# Time Manipulation ## block.timestamp Manipulation Validators/miners have limited control over `block.timestamp`: - Must be greater than parent block's timestamp - Must be within ~15 seconds of real time (consensus rule) - Post-merge: fixed 12-second slots, but validator chooses timestamp within bounds ```solidity // Safe for: time ranges > 15 seconds // Unsafe for: precise sub-minute timing, randomness // VULNERABLE: exact-second conditions if (block.timestamp == auctionEnd) { ... } // may never be true // SAFE: range-based conditions if (block.timestamp >= auctionEnd) { ... } // will always become true ``` ## Time-Dependent Logic Risks ### Unlock Schedule Gaming ```solidity // VULNERABLE: cliff unlock at exact timestamp function claimVested() external { if (block.timestamp < cliff) revert NotVested(); uint256 amount = totalAllocation; // full amount at cliff _transfer(msg.sender, amount); } // Risk: validator can set timestamp to just past cliff in their block // This allows early claiming relative to wall clock time // SAFE: linear vesting reduces impact of timestamp manipulation function claimVested() external { uint256 elapsed = block.timestamp - vestingStart; if (elapsed == 0) revert NotVested(); uint256 totalDuration = vestingEnd - vestingStart; uint256 vested = totalAllocation * Math.min(elapsed, totalDuration) / totalDuration; uint256 claimable = vested - alreadyClaimed[msg.sender]; if (claimable == 0) revert NothingToClaim(); alreadyClaimed[msg.sender] += claimable; token.safeTransfer(msg.sender, claimable); } ``` ### Cooldown Bypass ```solidity // VULNERABLE: short cooldown can be bypassed by timestamp manipulation uint256 public constant COOLDOWN = 30 seconds; mapping(address => uint256) public lastAction; function doAction() external { if (block.timestamp - lastAction[msg.sender] < COOLDOWN) revert Cooldown(); lastAction[msg.sender] = block.timestamp; // A validator can set timestamp 30s ahead to bypass cooldown } // SAFER: use block numbers for short cooldowns uint256 public constant COOLDOWN_BLOCKS = 3; // ~36 seconds mapping(address => uint256) public lastActionBlock; function doAction() external { if (block.number - lastActionBlock[msg.sender] < COOLDOWN_BLOCKS) revert Cooldown(); lastActionBlock[msg.sender] = block.number; } ``` ## Epoch Boundary Attacks Protocols with discrete time periods (epochs, rounds) are vulnerable at boundaries. ```solidity // VULNERABLE: reward rate changes at epoch boundary function getRewardRate() public view returns (uint256) { uint256 epoch = block.timestamp / EPOCH_DURATION; return epochRewardRates[epoch]; } // Attack: validator manipulates timestamp to straddle epochs // Deposit at end of high-reward epoch, claim, withdraw at start of next // DEFENSE: actions locked near epoch boundaries uint256 public constant BOUNDARY_BUFFER = 5 minutes; function deposit(uint256 amount) external { uint256 timeInEpoch = block.timestamp % EPOCH_DURATION; if (timeInEpoch > EPOCH_DURATION - BOUNDARY_BUFFER) revert NearEpochBoundary(); if (timeInEpoch < BOUNDARY_BUFFER) revert NearEpochBoundary(); // safe to deposit } ``` ## Dutch Auction Time Manipulation ```solidity // Dutch auction: price decreases over time // Validator can manipulate timestamp to get a lower price function getCurrentPrice() public view returns (uint256) { uint256 elapsed = block.timestamp - auctionStart; if (elapsed >= auctionDuration) return reservePrice; uint256 priceRange = startPrice - reservePrice; return startPrice - (priceRange * elapsed / auctionDuration); } // Impact: validator gains at most ~15 seconds of price decrease // For most auction speeds, this is negligible // For very fast auctions (price drops rapidly), use block numbers instead ``` ## block.number vs block.timestamp | Feature | block.number | block.timestamp | |---------|-------------|-----------------| | Manipulation | Not manipulable | ~15s drift | | Precision | Per-block (12s) | Per-second | | Cross-chain | Inconsistent | More consistent | | Post-merge | Fixed interval | Fixed interval | | Use for | Short cooldowns, ordering | Long durations, deadlines | ```solidity // block.number: use for short-duration, manipulation-sensitive logic // block.timestamp: use for long-duration, human-readable deadlines // Short cooldown: use blocks uint256 public constant WITHDRAWAL_DELAY_BLOCKS = 50; // ~10 minutes // Long deadline: use timestamp uint256 public constant PROPOSAL_DURATION = 7 days; ``` ## Safe Time Patterns ### Time-Locked Actions ```solidity struct TimeLock { uint48 executeAfter; bool executed; } uint256 public constant MIN_DELAY = 2 days; mapping(bytes32 => TimeLock) public timelocks; function schedule(bytes32 actionId) external onlyOwner { timelocks[actionId] = TimeLock({ executeAfter: uint48(block.timestamp + MIN_DELAY), executed: false }); emit ActionScheduled(actionId, block.timestamp + MIN_DELAY); } function execute(bytes32 actionId) external onlyOwner { TimeLock storage lock = timelocks[actionId]; if (lock.executeAfter == 0) revert NotScheduled(); if (lock.executed) revert AlreadyExecuted(); if (block.timestamp < lock.executeAfter) revert TooEarly(); lock.executed = true; _executeAction(actionId); } ``` ### Deadline Pattern ```solidity modifier beforeDeadline(uint256 deadline) { if (block.timestamp > deadline) revert Expired(deadline); _; } // Always use >= for "ready" checks, > for expiry checks function isReady(uint256 readyAt) internal view returns (bool) { return block.timestamp >= readyAt; } function isExpired(uint256 deadline) internal view returns (bool) { return block.timestamp > deadline; } ``` ### Rate Limiting ```solidity struct RateLimit { uint48 lastAction; uint16 actionsInWindow; } uint256 public constant WINDOW = 1 hours; uint256 public constant MAX_ACTIONS_PER_WINDOW = 10; mapping(address => RateLimit) public rateLimits; function checkRateLimit(address user) internal { RateLimit storage limit = rateLimits[user]; if (block.timestamp - limit.lastAction > WINDOW) { // New window limit.actionsInWindow = 1; limit.lastAction = uint48(block.timestamp); } else { if (limit.actionsInWindow >= MAX_ACTIONS_PER_WINDOW) { revert RateLimitExceeded(); } limit.actionsInWindow += 1; } } ``` ## Time Safety Checklist - [ ] No exact-time equality checks (`==` on timestamps) - [ ] `>=` for "ready" checks, `>` for expiry checks - [ ] Short cooldowns use block numbers, not timestamps - [ ] Long durations use timestamps for readability - [ ] Linear vesting preferred over cliff vesting (reduces manipulation impact) - [ ] Epoch boundaries have buffer zones - [ ] Deadline parameters on all time-sensitive user operations - [ ] Timelocks have minimum delays that cannot be reduced by governance - [ ] No use of `block.timestamp` for randomness - [ ] Dutch auctions: price decrease per 15s is acceptable loss