[DO NOT MERGE] Flow Core Contracts: Mainnet → Master upgrade diff

[vishalchangrani]

⚠️ DO NOT MERGE — Review Only

This PR shows the exact diff between what is currently deployed on Flow mainnet and what will be deployed in the upcoming core contract upgrade for this repository.

How to read this PR: The base is master (target) and the head is vishal/mainnet-deployed (current mainnet snapshot), so the diff is inverted compared to a normal PR:

• Red (deletions) = new code being introduced in the upgrade (what master adds)
• Green (additions) = old code being replaced (what is currently on mainnet)

---

Contracts by Risk Level

🔴 SUBSTANTIVE — Logic/behavior changes

Contract	Change	Risk
FlowFees	New child fee accounts feature — fee collection distributed across child accounts round-robin; collectFeesOnChildAccounts() added, getFeeBalance() aggregates across accounts, withdrawTokensFromFeeVault() completely rewritten	High
FlowIDTableStaking	Division-by-zero fix in reward calculation when all nodes are non-operational + .keys → direct dict iteration	Medium
FlowStakingCollection	saturatingSubtract prevents underflow panic when vault balance < minimum storage reservation (3 occurrences)	Low-Medium
FlowTransactionScheduler	Binary search break added on duplicate canceled ID; .keys → direct iteration	Low
FlowTransactionSchedulerUtils	Force-unwrap removed (index! → if let index)	Low

✅ COSMETIC — Error messages, comments, formatting only

Contract	Change
FlowExecutionParameters	Comment-only changes
StakingProxy	Error message improvements
FlowDKG	Error message improvements
FlowClusterQC	Error message improvements + quorum threshold comments
FlowEpoch	Error message improvements + safety comments
NodeVersionBeacon	Error message improvements
RandomBeaconHistory	Error message improvements
FlowServiceAccount	Error message improvements
LockedTokens	Error message improvements
FlowToken	Error message improvements + performance optimization comments

---

⚠️ Key Items for Reviewers

1. FlowFees has the largest and highest-risk change — a completely new child fee accounts feature that changes how every transaction fee is collected and withdrawn. This needs the most careful review.
2. FlowStakingCollection fixes a potential underflow panic with saturatingSubtract — safe and important bugfix.
3. FlowIDTableStaking fixes a division-by-zero edge case in reward calculation when all nodes are non-operational.
4. FlowTransactionScheduler / Utils are minor defensive fixes with low risk.

---

Mainnet Addresses

Address	Contracts
0x8624b52f9ddcd04a	FlowIDTableStaking, FlowClusterQC, FlowDKG, FlowEpoch
0xe467b9dd11fa00df	FlowServiceAccount, NodeVersionBeacon, RandomBeaconHistory, FlowTransactionScheduler, FlowTransactionSchedulerUtils
0xf919ee77447b7497	FlowFees
0x1654653399040a61	FlowToken
0x8d0e87b65159ae63	LockedTokens, FlowStakingCollection
0x62430cf28c26d095	StakingProxy
0xf426ff57ee8f6110	FlowExecutionParameters

---

Note: This PR is for review purposes only and should NOT be merged. The head branch (vishal/mainnet-deployed) is a snapshot of the contracts currently live on mainnet, fetched via flow CLI. It can be deleted after the upgrade review is complete.

For the EVM bridge contract upgrade diff, see: onflow/flow-evm-bridge#210

🤖 Generated with Claude Code