Mainnet Follow

You can keep select state on your Stagenet synced to the live chain it replays.

Normally, during Mainnet Replay, state modified on your Stagenet is preserved. Once a transaction changes an account, balance, contract, or storage slot, that modified state stops syncing from the replayed chain.

Followed state is different. If you follow an account, token balance, or storage slot, it continues reading from the live chain even after Stagenet transactions touch it. Any writes made to followed state during a Stagenet transaction are used for that transaction, then discarded when execution finishes.

When to follow mainnet state

Unmodified state already follows the replayed chain. This keeps prices, balances, oracle data, and protocol state up to date until you set them in a transaction.

For your own contracts and wallets, persistence is usually what you want. If you deploy a contract, fund a wallet, or run a test transaction, those changes should remain on your Stagenet.

For third-party state, this persistence can cause drift.

For example:

• A swap through a Uniswap pool changes the pool price on your Stagenet. On the live chain, arbitrage and ongoing activity may move the pool back in line. On your Stagenet, that may not happen automatically.
• Aggregators and pricing APIs may quote against live chain state, while your Stagenet executes against modified pool state. If the difference becomes too large, swaps can revert on your Stagenet even when they would work on the live chain.

Following mainnet removes this drift:

• Modified state — preserved on the Stagenet
• Followed state — kept synced to the live chain

How following works

When you follow an account, token balance, or storage slot, Mainnet Follow changes how that state is read and persisted during replay.

At the start of each block, the first read of followed state returns the live value from the chain your Stagenet is replaying. Any previously modified Stagenet value for that state is ignored.

Writes still behave normally inside the block. If a transaction writes to followed state, later reads in the same transaction see that written value. Later transactions in the same block can see it too. This preserves normal EVM behaviour for transactions that write and then read state during execution.

At the end of the block, writes to followed state are discarded instead of being persisted on the Stagenet. When the next block starts, the first read of that followed state returns the live value from the replayed chain again.

How to follow mainnet state

Mainnet following is performed via the CLI:

# Follow an account: every slot, account field, and code
contract.dev follow 0xc9034c3E7F58003E6ae0C8438e7c8f4598d5ACAA
 
# Follow an account's ERC20 balance
contract.dev follow 0xToken --balance-of 0xHolder
 
# Follow slots via decimal key
contract.dev follow 0xMyContract --slots 0,1,4
 
# Follow slots via 32-byte key
contract.dev follow 0xMyContract --slots 0x6e91f60197c982353033e86512311820683e018e0f39963c5d00c2c490bc45d3
 
# Stop following (mirrors the follow flags)
contract.dev unfollow 0xc9034c3E7F58003E6ae0C8438e7c8f4598d5ACAA
contract.dev unfollow 0xToken --balance-of 0xHolder
contract.dev unfollow 0xMyContract --slots 0,1,4

See the full details in the command’s reference: