Local Chain Time Manipulation Tool

WHAT IT DOES

Local Chain Time Manipulation Tool is a read-only developer tool that simulates blockchain time manipulation for local fork environments. It reads the current block timestamp from the latest block, calculates the effect of time offsets (forward or backward), and generates ready-to-use time manipulation commands for Hardhat and Anvil/Foundry. The tool helps developers test time-dependent contract logic (vesting schedules, timelocks, auctions, staking rewards) without waiting for real time to pass, by simulating time jumps and providing clear visual feedback on the impact of time shifts. It is essential for developers testing time-sensitive smart contract features in local development environments.

HOW TO USE

Connect your EVM-compatible wallet via the BGWallet bridge and select the network where your local fork is running. Enter a time offset in seconds (positive to jump forward, negative to go backward) and optionally provide a contract address to check state before and after the time shift. Click "Simulate Time Shift" to calculate the new block timestamp and generate time manipulation commands. Results include the current and new timestamps, human-readable time difference, commands for Hardhat (evm_increaseTime + evm_mine) and Anvil/Foundry (evm_increaseTime + evm_mine), and a visual time bar showing the offset direction. If a contract address is provided, the tool also reads its balance and contract status. All analysis is read-only—no signatures or transactions are submitted.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to fetch the latest block via provider.getBlock('latest') and extract the block timestamp. The user-provided offset is added to the current timestamp to calculate the new timestamp. Both timestamps are converted to ISO strings for human-readable display. If a contract address is provided, the tool fetches the contract's balance via provider.getBalance(address) and bytecode via provider.getCode(address) to determine if it's a contract. The tool generates time manipulation commands using the EVM's built-in time manipulation RPC methods: evm_increaseTime (which advances the block timestamp by the specified number of seconds) followed by evm_mine (which mines a new block with the updated timestamp). For Hardhat, the commands are formatted as JavaScript with hre.network.provider.send(). For Anvil/Foundry, the commands are formatted as cast rpc calls. The tool provides a visual time bar showing the offset direction and magnitude. The simulation does not actually manipulate chain time—it only calculates and presents the commands for the user to run in their local fork environment.

WHAT IT CANNOT SEE

This tool has fundamental limitations that users must understand. It cannot actually manipulate chain time—the tool is a simulation only and does not execute evm_increaseTime or evm_mine RPC calls. It requires a local fork environment (Hardhat, Anvil, or Ganache) with the evm_increaseTime RPC method enabled. It cannot guarantee that time manipulation will work consistently across all fork tools—different tools may implement time manipulation differently or have different RPC method names. It cannot persist time changes across fork restarts—time is reset when the fork is restarted. It cannot manipulate time on live networks—time manipulation is only possible in local fork environments. It cannot automatically adjust contract state that depends on time without manual intervention—the tool only generates commands, it does not execute them. It cannot handle complex time-dependent scenarios (e.g., multiple contract dependencies) without manual testing. It cannot detect contracts that rely on block.timestamp in ways that are not easily testable with time manipulation. It cannot simulate time-dependent events that require specific block numbers in addition to timestamps. The tool's commands are templates and must be manually executed in the appropriate environment.

PLEASE NOTE

This tool only supports EVM-compatible blockchains (Ethereum, Polygon, BSC, Avalanche C-Chain, Optimism, Arbitrum, and their testnets). Solana, Tron, Starknet, SUI, TON, Aptos, Bitcoin, Cosmos, and XRP are not supported. The tool is free, open-source, requires no API keys, and uses the wallet's native provider for all read operations. Time manipulation is a powerful testing feature—always verify contract behavior at multiple time points to ensure correctness.