Mainnet Replay
Mainnet replay keeps a Stagenet in step with the chain it copies. It replays two things:
- Mainnet state, so everything your own transactions haven’t touched stays up to date with mainnet.
- Selected mainnet transactions, so real user and DeFi activity runs on your Stagenet when you need it.
Everything your own transactions change is kept.
State replay
A new Stagenet starts from the chain’s latest block, with all of its state: every contract, balance, pool and price. From there it replays the chain’s new blocks one after another. For each block, the Stagenet:
- Runs the transactions your team has sent to it.
- Brings all the state your transactions haven’t touched up to date with mainnet.
Oracle prices move, pools trade and balances change on your Stagenet as they do on mainnet. Your deployments and test transactions stay where you left them.
Untouched and modified state
| State | On each replayed block | Example |
|---|---|---|
| Untouched: never changed by a Stagenet transaction | Keeps updating from mainnet. | A Chainlink price feed updates on Ethereum, and the same update reaches your Ethereum Stagenet. |
| Modified: changed by a Stagenet transaction | Kept as your transaction left it, and no longer updated from mainnet. | You swap through a Uniswap pool. From then on, that pool’s reserves and price belong to your Stagenet. |
Transaction replay
As a Stagenet runs, it can also replay selected sets of mainnet transactions. State replay copies the results of mainnet’s transactions. Transaction replay runs the transactions themselves again, on the Stagenet, against its own state, including the contracts and state you have changed.
This brings real user and DeFi activity onto your Stagenet when you need it. For example, you could replay:
- Every transaction sent to your protocol’s contracts, so real users’ deposits, borrows and withdrawals run on your Stagenet.
- Swaps through the pools your protocol depends on, so they keep trading against the state on your Stagenet.
- Activity from a set of wallets, such as your largest users or a market maker.
To test an upgrade, deploy it on a Stagenet, then replay your protocol’s mainnet transactions as they happen. Your real users’ activity now runs against the new code, and you can see how it handles that activity before the upgrade ships.
Block context
Transactions on a Stagenet run inside the block being replayed:
block.numberandblock.timestampfollow that block, so time-dependent contracts behave as they would on mainnet at that moment.- Gas price and base fee follow it too.
- The chain ID is the Stagenet’s own, so wallets treat it as a separate network.
Staying close to mainnet
Modified state drifts. A test swap moves a pool’s price on your Stagenet. On mainnet, arbitrage moves it back, but on the Stagenet it stays moved. Over days of testing, swaps quoted against mainnet prices (by an aggregator, for example) start to revert on the Stagenet, and market-maker inventories drain without refilling.
Two controls keep a long-running Stagenet close to mainnet:
- Follow: keep selected state, such as a pool, an oracle or a single token balance, synced to mainnet even after your transactions touch it. Your writes apply within a block and are discarded when it ends.
- Reset: return all third-party state to mainnet in one step, now or on a schedule. Your wallets keep their balances, approvals and nonces, and the chain does not rewind.